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.
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.
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.
Yes, it is the primary medium to communicate to you users. You may have an API service or an installable library or an application, but your documentation quality matters when you think about retaining old users and getting new one!
Above is an old sketchnote I did, happiness of the users matters most and it can only come with providing a superb documentation along with your application/API.
Documentation comes in different forms, for the users first thing is a quickstart docs, something which can tried within 5-10 minutes, then comes tutorials and how-to guides, which can vary from 30 minutes to couple of hours to complete. API documentation comes after that, mostly for your experienced users, in-depth details and examples should be part of it.
There are many projects who will not accept a patch without the necessary documentation changes along with it. If you look into projects like Django or Qt , you will understand why they have such big userbase. Along with the excellent product, they provided world class documentation. There is another point which these projects teach, who should write the initial documentation?
You read correct, not any new contributors but the developers themselves. As a developer, you already have better idea of the project and how it works, if you write the initial documentation that will help more for new contributors than them trying to find out how things work and then write the docs.
In next part I will discuss more on code comments.