Document your code: Part 2

So we saw benefits of having documentation in the last post . In this post I will go through another topic we discuss a lot, code comments or not!

Let us look into a more common thing first. Look at the handwriting below and think if you have to read some notes/answer sheet/ideas, which side of the text you want it to be like? Left or Right?

Text from left hand side, you can read and understand. What about the right hand side text? Do you really want to read a 10 page long document in that handwriting? Now use the same ideas into the code you read regularly. People read a piece of code a many times than you think. (Btw, the right hand side was my own handwriting few months back.)

If you can not read your code without comments that means you are surely doing it in a wrong way, it is just bad code. You can think about comments as the extra toppings on top of your regular pizza, but it can not become your regular pizza (i.e. your code). Think about a world where comments do not exist, you have to name your variables right, refactor the code till it becomes obvious so that others can read and understand. Remember the Zen of Python

Simple is better than complex.

– Zen of Python

Also remember that the comments are for human reader, they are not for the interpreters or compliers. There are many cases where a long comment will confuse the reader more than helping. This brings in another favorite quote.

to write good comments you have to be a good writer.

– Jeff Atwood

But you may still want to have comments for other reasons. Let us look into some of those cases.

• I want to track all changes in the code. Sorry, wrong place, VCS/SCM exists for that particular reason. Use nicer commit messages so that later when you read back your log history, you will thank yourself.
• I want to use this commented code in future. Once again, you can get that back from your VCS/SCM. You don’t want it lying around inside your code. Just remove it and keep the code clean.
• Reading English is easier than my programming language. We are programmers, we can understand code much better than anyone else.
• To find a piece of code. You can use any modern text editor (vim, emacs or sublimetext) and find symbols, classes very fast. Just learn to use your editor properly or choose a better one.
• What about TODO entries? This still makes sense while you are developing, but remember not to add a chapter of a book there.

Let us now look into a proper code comment example. Below are the lines from io.py in CPython.

# Declaring ABCs in C is tricky so we do it here.
# Method descriptions and default implementations are inherited from the C
# version however.
class IOBase(_io._IOBase, metaclass=abc.ABCMeta):
    pass

Now you can clearly see that there is no easy of saying that ABCs are tricky through your code, so the authors chose two simple English statements to explain it all.

The last point to discuss is about having comments or name variables in your code in your mother tongue (other than English). Bad idea, you really don’t know the future. The next person who will read your code might be from another part of the world, English is the standard language for all of the programmers, try to follow the same path.

Please share your thoughts on the same as comments here or reply on twitter. In the next post I will look into docstrings in Python code.