The other day I talked to a collegue about some technical details and doing this I took notes directly in code. When we finished this collegue asked me not to delete these comments. A little peculiar in itself (who would have done such a thing?) in this particular case the comment had a double meaning: The code being some more or less complex mapping of numeric ranges would not have been comprehensible without comments. And in my opinion incomprehensible code is worse than bad code. Bad code can be fixed after all.
About the same time I stumbled over an article that pointed to “Proof reading is more important than composition“. The authors opinion about readability is something to applaud. All the more irritating how wrong his conclusions are (just my opinion of course!). He deprecates coding conventions as being of adverse effect for readability. Having worked on software in teams of up to 80 developers and of different age (in terms of versions and maintenance impact) I am accustomed to read and evolve existing code as well as write code that has to be understood by other developers after I have moved on. And of one thing I am certain: Coding conventions are a necessary requirement for readability. Of course they are not sufficient, but do away with them and readability will follow shortly. All it needs is the next developer working on the code and using his personal coding style. This has to happen only once, no way to put the chicken back in the egg.
While the author of this article started with a right assumption and quickly got it wrong, the author of the article that pointed to it did the opposite: He started with a wrong assumption (“few people actually … are going to come back and read that code” — if the code matters, people will come back) but he quickly gets it right. I especially like his distinction between programmers and developers:
- Programmers write code to solve problems
- Developers write code that can be read by other people and to solve problems
I recommend reading that post because the author makes some good points getting there and even better ones based on that statement.