Comments and Readability

Most folks who deal with computers would agree that the top priority for a computer program is that the computer can run it. I think of this as computer readability. If the Python interpreter can't read a program, it won't run and will throw an error, usually a syntax error.

In the past I have assumed this is the be-all and end-all of readability - as long as Python understands the program nothing else needs to understand the program. As I am not yet a professional programmer, so far (until I started this blog) I was the only one who had to read the programs I wrote.

Problems arose when I had written a program that was either quite complicated (at least by my standards) or involved something new that I had recently discovered in a textbook or web forum. I would be okay writing it (maybe after some trial, error and debugging) and while this process was going on I would be aware of the concepts I was trying to implement.
But if I came back to the program a week or a month later and looked at what I had done, the techniques, structures and functions I had been juggling in my head had by then faded away. I had to look at my code and work out what I had done.
Even if nobody else was looking at my code, I realised that human readability was useful for my own understanding of my own programs. I have borrowed a number of techniques that have helped me with my own programs and I hope will allow others to follow my coding more easily.

• Don't be afraid to comment as often as you want to. Although different programmers will have different ideas of how much comment is appropriate there have been a few of my programs where there has been more comment than Python-readable code. Some may say that's too much, but if I'm the only one reading the code, then it's up to me. 
• As I have become more familiar (fluent?) with Python, there are a number of basic expressions that I don't need to comment on - I am more likely to use comments on or around lines that I might struggle with. I may also comment on the bigger picture of how different parts of the program hang together, particularly when it is not obvious from the code itself. Sometimes the comments are not so much what I am doing in the code so much as why I am doing it. 
• Appropriate and descriptive names. Currently the main names I have used on this blog are variables, though later on there will be functions and classes that the programmer gives names to. Although typing out long names is a bit more tiresome than short ones (and there is an increased chance of spelling errors), being given a clue what the name represents makes programming a lot clearer for me and makes logical errors less likely. In professional circles this is known as self-documenting code. Of course, it's sensible not to have names too long (whether variable, function or class) and if you want you can keep it short and sweet, with a comment at the start or when the name is defined/initialised to explain what it is. 
• If a line of code starts looking so long, complicated and convoluted I am no longer sure what it means, I will try to split it up into two or more simpler lines. If that means I have to create a new variable to pass a value on from one line to another, so be it. I know some programmers try to get as much code onto a single line as possible, with expressions nested inside other expressions. That's okay up to a point. But it becomes like a sentence in English that is a paragraph long, full of phrases, conjunctions, transitions and structures. It's easier just to add a few full stops and split it into shorter sentences. 
• Superfluous and unnecessary code should be eliminated. I have sometimes used the comment hash # to temporarily disable lines of code while I am debugging or experimenting. This is fine in the short term, but when I have decided that line really shouldn't be there I delete it rather than leave it there hashed out. Similarly if possible I will implement things directly rather than in a round-about way, keeping it to as few lines as feasible (while bearing in mind the point above this one). 

In companies and organisations where code is shared and maintained by lots of people, readability becomes very important. Although I have not yet needed to deal with the matter directly, I have heard that companies often have their own style guides saying how code should be made readable in a consistent way.

A lot of programmers using other languages will say that indentation is important for human readability. As we have seen, in Python it is necessary for computer readability - your program won't work (or at least not as expected) if you don't get indentation right according to the Python interpreter. This has the effect (I'm sure it is intentional) of making Python code easier to read.