Moving from Python 2.7 to 3.x is covered in much more detail here. This list is just a list of items I’m checking as I make the switch. It’s somewhat reflective of my own coding style and is meant more as a checklist for myself than anything, but if it helps you, great!

• Change print to print().
• Change xrange to range.
• Change raise, Execption "Message" to raise Exception("Message").
• Change from module import x to from .module import x, if module is a relative import and not on the PYTHONPATH. If I’m importing the entire module, it’s now from . import module.
• Anywhere there is integer division being used, change it from / to //.
• If I use the result of range(...) as a list, explicitly convert it to a list, e.g., list(range(...)).

Students in introductory programming courses sometimes feel, “What’s the use in commenting? The important part is getting the program to run.” Some students also feel, “Adding too many comments clutters the code.” As a result, there’s a tendency to avoid commenting or to do the minimum required.

Commenting, however, is a vital part of programming, as commenting is what makes your code useful to others (including yourself a month later). If you don’t comment your code, no one else can pick up your code and understand it. Think of it this way. If a company hires you to write some code and you leave the company after writing it, if you didn’t comment your code, how will your replacement understand what you did? And if your replacement has to rewrite your code because no one can understand it, didn’t your company just waste its money on your salary? As a result, no software development company will let someone contribute code that is poorly documented.

That being said, I admit you can overcomment. Especially when we’re first learning how to comment, we will tend to provide more details than are necessary. Still, if you’re just starting to learn how to program, I’d encourage you to overcomment rather than undercomment. At this stage, you need to get into the habit of writing comments. At this stage, the only way to do so is to write more than less. As you gain more experience in programming, you’ll get a better sense of what needs to be included and what doesn’t. But you can’t get to that stage if you scrimp on commenting now.

It’s like learning to write essays. As a second-grader, when your teacher asked you to write about your favorite pet or what you did over Spring Break, they didn’t say, “make sure you only use active voice and be as concise as possible.” No, they just wanted you to write as much as you could. Only later in school did your teachers say, “be concise, etc.” The same thing is true with comments. At this point, you need to create the habit of commenting, even if you don’t want to and feel it’s a waste of time. Describe what goes into a method, what comes out, the state of the program going in, the state coming out, and what gets changed and how. If you feel you’re saying too much, that’s okay. Later on, you’ll learn about what to leave out.

In this post, I’m going to give you advice that I am nearly sure you will ignore. The reason I know this is because most people I’ve given this advice to, I’m nearly sure, ignored it. I doubly know this because it took me years—nay, maybe over a decade—for me to start listening to this advice. So, believe me, I won’t be offended if you ignore this advice. Continue reading →