Add section on errors and descriptions of Python versions #131
Conversation
keeping my version of PLYMI up to date with the current version
|
I reread issue #110 and #66, and I think adding a bit more to this would be appropriate to fix those issues. Slightly expanding the discussions of ‘raise’ and ‘assert’ would definitely be in order, as would slightly more analysis of reading traceback messages. I also think this is a good spot to add the walrus operator, since this discusses the versions of Python. I’ll make a few commits later tonight - |
|
In general, I like to leave issues open until they are fully resolved Edit: whoops I thought this was an issue. FYI when you create a PR you can set it as: work in progress |
|
Got it - I'll do that when I make the next PR. Should be up sometime in between today and Tuesday |
|
|
||
| All Python versions numbers use the A.B.C format. The three numbers denote major releases, minor releases, and patches. | ||
|
|
||
| - The first number denotes major releases to the language. The most current major release is Python 3, but Python 2 is still in use. When a major release comes out, it means that older code will not work with the new release. Running Python 2 code in a Python 3 interpreter will yield errors, as will running Python 3 code in a Python 2 interpreter. Although Python 2 is still used in many legacy applications, Python 3 is much more modern and is more widely used. |
There was a problem hiding this comment.
| - The first number denotes major releases to the language. The most current major release is Python 3, but Python 2 is still in use. When a major release comes out, it means that older code will not work with the new release. Running Python 2 code in a Python 3 interpreter will yield errors, as will running Python 3 code in a Python 2 interpreter. Although Python 2 is still used in many legacy applications, Python 3 is much more modern and is more widely used. | |
| - The first number denotes major releases to the language. The most current major release is Python 3, but Python 2 is still in use. When a major release comes out, it means that older code may not work with the new release. Running Python 2 code in a Python 3 interpreter may yield errors, likewise for running Python 3 code in a Python 2 interpreter. Although Python 2 is still used in many legacy applications, Python 3 is much more modern and is more widely used. |
More importantly, Python 2 is deprecated and not supported at all. Do we want to talk about it at all? I forget what's been said about it already
There was a problem hiding this comment.
As far as I can find, there isn't any current mention of Python 2. Seems like about 15% of Python people are still stuck on Python 2, so I think it bears mention? That being said, it should be clearer in that section that Python 2 is deprecated and that people should only really be using Python 3.
There was a problem hiding this comment.
@HardBoiled800 this material on Python versioning should be a separate PR. PRs should generally be monolithic.
| All Python versions numbers use the A.B.C format. The three numbers denote major releases, minor releases, and patches. | ||
|
|
||
| - The first number denotes major releases to the language. The most current major release is Python 3, but Python 2 is still in use. When a major release comes out, it means that older code will not work with the new release. Running Python 2 code in a Python 3 interpreter will yield errors, as will running Python 3 code in a Python 2 interpreter. Although Python 2 is still used in many legacy applications, Python 3 is much more modern and is more widely used. | ||
| - The second number denotes a minor release. When a minor release comes out, older code will run in the new interpreter, but new code will not necessarily be compatible with older versions. Python 3.7 and 3.8 are great examples of this - any code that works in Python 3.7 will run in Python 3.8, but new syntax has been added that will not work with Python 3.7. |
There was a problem hiding this comment.
| - The second number denotes a minor release. When a minor release comes out, older code will run in the new interpreter, but new code will not necessarily be compatible with older versions. Python 3.7 and 3.8 are great examples of this - any code that works in Python 3.7 will run in Python 3.8, but new syntax has been added that will not work with Python 3.7. | |
| - The second number denotes a minor release. When a minor release comes out, older code will run in the new interpreter, but new code will not necessarily be compatible with older versions. Python 3.7 and 3.8 are great examples of this - any code that works in Python 3.7 will run in Python 3.8, but new syntax has been added that will not work in Python 3.7. |
| <!-- #region --> | ||
| ## Syntax Errors | ||
|
|
||
| Syntax errors are by far the easiest errors to debug, and they will be the most common errors while you are learning to program. Syntax errors are raised when the Python interpreter is unable to understand your code due to a typo or some misplaced syntax. When a syntax error occurs, the interpreter will stop running. It will also display the `SyntaxError` code, and will often give a line number or explanation. |
There was a problem hiding this comment.
| Syntax errors are by far the easiest errors to debug, and they will be the most common errors while you are learning to program. Syntax errors are raised when the Python interpreter is unable to understand your code due to a typo or some misplaced syntax. When a syntax error occurs, the interpreter will stop running. It will also display the `SyntaxError` code, and will often give a line number or explanation. | |
| Syntax errors are by far the easiest errors to debug, and they will be the most common errors while you are learning to write code. Syntax errors are raised when the Python interpreter is unable to understand your code due to a typo or some incorrect syntax. When a syntax error occurs, the interpreter will stop running. It will also display the `SyntaxError` code, and will often give a line number or explanation. |
Have we talked about what syntax actually means before this?
There was a problem hiding this comment.
Unsure if there's been a strict definition, but the word is definitely used many times before this. Regardless I can make it a bit more clear.
|
|
||
| Syntax errors are by far the easiest errors to debug, and they will be the most common errors while you are learning to program. Syntax errors are raised when the Python interpreter is unable to understand your code due to a typo or some misplaced syntax. When a syntax error occurs, the interpreter will stop running. It will also display the `SyntaxError` code, and will often give a line number or explanation. | ||
|
|
||
| Most syntax errors are benign and easily detectable, such as mispelling a name or forgetting a piece of punctuation. Occasionally you will encounter a tricky syntax error where you cannot find your mistake in the line. When this happens, remember to look out for punctuation mistakes, especially in parentheses. Misplaced parentheses can be difficult to detect, but are relatively simple to fix once detected. |
There was a problem hiding this comment.
| Most syntax errors are benign and easily detectable, such as mispelling a name or forgetting a piece of punctuation. Occasionally you will encounter a tricky syntax error where you cannot find your mistake in the line. When this happens, remember to look out for punctuation mistakes, especially in parentheses. Misplaced parentheses can be difficult to detect, but are relatively simple to fix once detected. | |
| Most syntax errors are easily detectable, such as mispelling a name or forgetting a piece of punctuation. Occasionally, you will encounter a tricky syntax error where you cannot find your mistake in the line. When this happens, remember to look out for punctuation mistakes, especially in parentheses. Misplaced parentheses can be difficult to detect, but are relatively simple to fix once detected. |
I wouldn't really call a syntax error benign since it will prevent your code from executing 🤔
There was a problem hiding this comment.
I would say it is benign in the sense that it doesn't lead to unexpected behavior in your program
|
|
||
| <!-- #region --> | ||
| ## Exceptions | ||
| An exception occurs when a piece of code is valid and understood by the interpreter, but for some reason the interpreter is unable to execute the action. Exceptions can occur when a function is passed an incompatible type of input, when the program is asked to something it cannot, and in many other circumstances. Python has many types of built-in exceptions that can be raised, but here are several that you are likely to encounter and their causes: |
There was a problem hiding this comment.
"...when the program is asked to something it cannot,..."
asked to do something it cannot? To compute something it cannot? Need some extra word in there
|
|
||
| Logic errors occur when your code will run in the interpreter, but does not behave as expected. Whenever you write a function that works but outputs something incorrect, you have committed a logic error. Logic errors are very easy to commit and can be incredibly difficult to solve. It's impossible to completely avoid logic errors, but if you take care while programming and debugging, they can often be avoided or fixed. | ||
|
|
||
| Before writing a complex program, it is often smart to write psuedocode beforehand to ensure that your algorithm makes sense and will do what you want it to. It is important to understand how your program will work before you write it. After writing the program, it can be helpful to take another walk through how the program works, and make sure that every step makes sense. Some programmers keep rubber ducks at their desks and try to explain their code to the duck when they hit a bug. Sometimes, simply walking through your code slowly and describing everything can help you see an error that you otherwise may have missed. |
There was a problem hiding this comment.
have we talked about pseudocode before this?
also placemark for myself because I want to revisit this
There was a problem hiding this comment.
Pseudocode isn't mentioned anywhere in the site as far as I can tell. Where do you think it would be good to include a discussion on pseudocode? I don't want to overcomplicate this section but it's definitely something we should talk about
|
|
||
| Before writing a complex program, it is often smart to write psuedocode beforehand to ensure that your algorithm makes sense and will do what you want it to. It is important to understand how your program will work before you write it. After writing the program, it can be helpful to take another walk through how the program works, and make sure that every step makes sense. Some programmers keep rubber ducks at their desks and try to explain their code to the duck when they hit a bug. Sometimes, simply walking through your code slowly and describing everything can help you see an error that you otherwise may have missed. | ||
|
|
||
| Breaking your code down into functions can help with readability, usability, and debugging, especially as the scale of your project grows. It is much easier to find the error in ten functions, each with fifty lines, than it is to find the error in one block of code that is five hundred lines long. Testing out different parts of your code independently to verify that they work is essential to debugging. |
There was a problem hiding this comment.
| Breaking your code down into functions can help with readability, usability, and debugging, especially as the scale of your project grows. It is much easier to find the error in ten functions, each with fifty lines, than it is to find the error in one block of code that is five hundred lines long. Testing out different parts of your code independently to verify that they work is essential to debugging. | |
| Breaking your code down into functions can help with readability, usability, and debugging, especially as the scale of your project grows. It is much easier to find an error in ten functions, each with fifty lines, than it is to find an error in one block of code that is five hundred lines long. Testing out different parts of your code independently to verify that they work is essential to debugging. |
might want to add a note here that says we'll discuss testing in more detail in Module 6
|
|
||
| Breaking your code down into functions can help with readability, usability, and debugging, especially as the scale of your project grows. It is much easier to find the error in ten functions, each with fifty lines, than it is to find the error in one block of code that is five hundred lines long. Testing out different parts of your code independently to verify that they work is essential to debugging. | ||
|
|
||
| To find particularly elusive bugs, many IDEs come with debugging software that allows you to step through your program slowly and monitor the internal processes. Debuggers can be overkill for simpler bugs, but they can be invaluable tools when you cannot find a bug on your own. |
There was a problem hiding this comment.
we haven't really said much here. We've mentioned debuggers exist but haven't really said what they do (e.g. what does it mean to "step through your program slowly"?). May want to note that this is a topic outside the scope of this website and optionally include some helpful links to pdb, etc.
There was a problem hiding this comment.
Haha part of this is because I am incredibly bad at using debuggers and barely understand how they work. I'll add some links
There was a problem hiding this comment.
@HardBoiled800 you ought not write instructional material about topics you "barely understand"! 😛 It is better to simply ask for someone else to contribute.
|
|
||
| To find particularly elusive bugs, many IDEs come with debugging software that allows you to step through your program slowly and monitor the internal processes. Debuggers can be overkill for simpler bugs, but they can be invaluable tools when you cannot find a bug on your own. | ||
|
|
||
| If all else fails, it's best to simply move on and return to the program after some time has passed. A bug that may seem impossible to fix may become much easier after a good night's sleep or a meal. |
There was a problem hiding this comment.
| If all else fails, it's best to simply move on and return to the program after some time has passed. A bug that may seem impossible to fix may become much easier after a good night's sleep or a meal. | |
| If all else fails, it's best to simply move on and return to the program after some time has passed. A bug that may seem impossible to fix may become much easier after a good night's sleep or a meal. |
not sure "move on" is the best phrasing here. Move on meaning just keep working while knowing your code is broken? Move on meaning take a break (which seems what's intended here)?
There was a problem hiding this comment.
I don't think that advice like "have a good night's sleep" fits in with the rest of the tone of PLYMI. To keep the material lean, I generally stick to material that provides guidance that is immediately actionable.
If there is a need to talk about methods for debugging, including high level aspects like taking a nap, I would prefer to simply link to a high-quality external resource. That topic deserves a lengthy discussion that includes stackoverflow, debuggers, print statements, and testing.
| - Exceptions occur when your code is readable, but cannot be run correctly | ||
| - Logic errors occur when your code runs, but does not behave as expected | ||
|
|
||
|
|
There was a problem hiding this comment.
have we talked about exception handling elsewhere (try/except)? If not, this should probably be added to this section
There was a problem hiding this comment.
We have not. I believe @HardBoiled800 is meaning to loop back to add that
|
Thanks for the awesome feedback @davidmascharka - I'll make sure to address all this before remaking the request |
There was a problem hiding this comment.
@HardBoiled800 it would be great if you could make clear to me what the learning objectives are for this section. Right now it gives the audience a sense for errors and lists some common exceptions, but it isn't totally clear how this discussion, in its current form, fits in with the essentials as they are conveyed by the rest of module 2.
It would be great if you could describe: Without this section, readers will not understand X and will not be able to do Y.
|
@rsokl thanks for the awesome feedback - I'll make sure to factor those changes into the next revision. As far as learning objectives, I would say that learning about exceptions will make readers better debuggers, and the sooner they understand how to tackle their errors the better. Without this section, readers will not understand the main causes of errors and will not be able to debug as effectively. This is definitely something that most people learn just by experience or trial-and-error. Perhaps this would be more appropriate in Module 5 than Module 2? I can see it fitting in either, but I'm not sure what you would deem as essential for Module 2. |
This pull request adds a full section to Module 2 about handling errors and would add a detailed explanation of Python versions to module 1. A new file is created for the section on errors, and an existing section is updated for the version explanation.
There are three commits in this pull request, but only two of them actually matter. Commit 7bf93d4 was just me updating mine to match the current master branch after it was updated earlier.