Comments: DOs and DONTs in Brief
First of all, a disclaimer: I have never been fond of writing extensive comments in source code. Nor do I expect others to write too many comments. If you write really clean code, your code should not require too much explaining to do.
- If you have to explain what a class, a method, or a variable does, perhaps a better name would be more valuable than a comment.
- If you have a function that is hard to understand because it does too many things, splitting it into smaller functions, with each function doing only one thing, is a better way than having to write plenty of comments.
Having said that, I am not against writing comments either. It would be naive to suggest that things like writing good names (for classes, functions, variables, etc) and writing small functions are enough to make code understandable.
Comments are valuable
- to provide a high-level overview of key steps and workflow in your code
- to explain inherent complexity of your implementation
- to explain strategic choices made by you
The real intention of this article is to introduce docco, a really cool tool for generating documentation from the comments in your source code. It’s so simple to install and run, that you can start using it in less than 15 minutes. I promise. And chances are that you will love it.
Docco extracts comments in your source code, and generates web pages from your source file, placing the comments in a readable manner alongside the code. Docco supports markdown to allow text formatting when building documentation.
In one of my earlier blogs on the Eight Queens Problem, I had described an algorithm and presented the Java code for finding the 12 distinct solutions to the problem, and printing those along with the derived solutions (90, 180 and 270 degree rotations; mirror image of the original and its 90, 180 and 270 degree rotations).
I reproduce the code from that post here, but embellished with comments that I believe make it easier to understand.
You must have the following installed on your machine:
- Python and the python package called ‘Pygments’. The easiest way is to install a pre-built Python distribution like ‘Anaconda’ which comes with Pygments (https://www.continuum.io/downloads)
- Nodejs (https://nodejs.org/en/), NPM (The Node Package Manager) comes bundled with a standard Nodejs installation.
Docco uses these runtimes to parse your code and provide syntax highlights.
To install docco globally, run the following on the command prompt:
Running docco to Generate Documentation
Go to the command prompt in the folder where you have the source code to comment, and then run the following command:
Docco creates a subfolder called “docs” under the current folder. In that folder, you will find a file called “EightQueens.html”. Open that file in your browser, and you will find the page appearing as shown below:
Docco is a first step towards the ‘literate programming’ approach for many languages. Literate programming (https://en.wikipedia.org/wiki/Literate_programming) is a paradigm introduced by Donald Knuth (http://www.literateprogramming.com/knuthweb.pdf). In a nutshell, it advocates that together the code (clean code!), comments and macros (if needed) must all be used to make the source lucid and easy to read, it must provide natural, continuous ‘flow’ (or exposition) of logic for the programmer reading the source code.
The experience of reading code should be as close to the experience of reading the text of an essay as possible. This, needless to say, contributes to better understanding of the system, resulting in fewer bugs and improves the maintainability of the code.
I hope this whets your appetite for docco. If you find docco interesting, you can find out all about it at https://jashkenas.github.io/docco/ , including the various ports for multiple languages, markdown support for formatting text with effects like bold, underline, list of bullet points, hyperlinks, etc.