I came across a good article over on the acmqueue site today. It deals with the question of whether good code is self documenting and whether comments in the code are needed. I had written about that subject before. The article points out that there are some who subscribe to the following point of view:
If you don’t understand my code, it doesn’t mean that it needs comments, it means you need to learn more about programming.
According to the article, the best programmers have the ability to find their way quickly, even in undocumented code and that this has been used by some to distinguish themselves:
In fact, the ability to look at a piece of code and perceive its overall structure and purpose without recourse to comments or design documents has often been the informal way to separate the best from the rest.
But then the article goes on to make two very good points. The first one being:
The reality of software development is that there is a much larger class of programmers who are good, but not that good. And unless you have had the immense good fortune to have a development team composed of nothing but programming ninjas, then your software development processes have to be geared to that broader class of software developers.
Open source projects should take note here. The code is open, so anyone can contribute. But not every interested contributor necessarily is a star programmer. Some will just be beginners, students even. Others will be motivated users who happen to care enough to submit a bug fix or small feature enhancement. Elitism has a long tradition in computing circles, and has been particularly evident in the open source communities for a long time. It also has been rightfully criticized before. For anyone interested in growing an open source project, such elitism is entirely misplaced. Growing the community is absolutely essential to any open source project. Don’t forget: The community of the project is a feature of the product. Why? Well, obviously, a thriving community indicates to a potential user that there is interest, support, and ongoing maintenance. Therefore, a potential user (customer?) needs to see this community as an important indicator of the long-term value of the project.
Consequently, every open source project is well advised to focus hard on building this community. In the case of open source, this is not only a user community, but also a developer’s community. This does not come for free, as I had written about before.
The second important point made by the article was explained by way of an example:
The code itself was simple to understand, but what the code could not communicate was why the code existed at all.
Couldn’t agree more with this point: It is not necessary to document what every single line does. But the reader of the code needs to understand why that line, function, object, file is present in the first place. This was also discussed in my posting here.
Consider the potential contributors with a bright idea. Faced with undocumented code they are left to guess to figure our why certain things are done in a particular way. Should they sit there with a bad taste in their mouth, because the code has essentially implied that they are not smart enough to be worthy of participating in the project? Is that a way to welcome a volunteer? Is that how you would want to greet someone who potentially adds significant value to your project? If not through a feature then just through their presence alone already?
No, I didn’t think so.
Therefore, building the bazaar is an exercise in rolling out the red carpet to the volunteers, which you hope to attract to your open source project. That means a lot of things, but good comments in the code are certainly one of them.