Commenting Code
Cedric is taking exception to Robert’s post that commenting code is often over-hyped. The comments to Cedric’s post are worth reading as well. To summarize: Robert thinks that it is better to write clear code than clear comments and the Cedric thinks that code gets read much more than it gets written, so that comments save time in the long run.
Two words: customer value. The idea that commenting code is an activity that has costs and benefits for whoever is paying for the software has been missed by both Cedric and Robert. There are points made that suggest an impact on value — such as junior developers learning faster by working on uncommented code — but the explicit connection to business value is entirely missed. Perhaps neither developer works for a commercial company that intends to generate revenue or improve internal processes through their software. Perhaps they both fill their days by writing open source software. But I doubt it.
In the context of software development in which an organization has spent resources with the expectation of generating value, discussions about the merits of development activities should be confined to the business value generated by those activities. Does the proposed value to the customer justify its costs?
So the value of code comments is situational, based on the business context of the project. If Cedric’s projects typically involve more code review than code authoring, then he may make a business case that an expenditure of time to increase the verbosity of the code’s comments can reduce the time to market and/or lower the defect rate, thereby reducing maintenance costs. If Robert’s projects involve extensive documentation external to the code, such as produced by planned methodologies, or his teams are responsible for maintenance and consist primarily of senior developers who write very readable code, he may be able to make a business case that a small increase in risk by limiting the verbosity of code comments can significantly reduce the time to market.
It’s the customer value, stupid.
