Are your code comments a way to say I’m Sorry for the actual code?
There’s a great post on perlmonks focused on the topic of comments in code. It fits with a lot of what we’ve been practicing here at Dovetail lately.
We often talk about the benefits of loose coupling, but I never really thought about the coupling that occurs with code and comments. The original post sums it up nicely:
One of the high priority goals in programming is the removal/avoidance of codependencies. We avoid using parallel data structures (eg.parallel arrays), because it becomes a nightmare to maintain those parallel arrays in synchronisation as algorithms and projects evolve. One of the key attributes of well designed classes (and other abstractions), is that they are as fully independent of their peers as possible. As decoupled as is possible to achieve.
By relying upon both code and comments to describe our algorithms, we are purposely coupling those two and creating a dependence upon that coupling; with all the caveats and consequences that entails.
The full post is lengthy, but worth the read. The comments are also interesting (commenting on the concept of eliminating comments…hmmm…)
Why do we focus on such concepts of testability and loose coupling? Sustainability. Again, the OP makes a great point:
In most cases of consequence, code spends much more of it’s life in maintenance than it does in development, and it is about time that corporations and individuals recognised that fact.
The maintenance of code seems to rarely be done by the original code author. I ran into this just this week.
I’ll quote Scott Bellware here: Programmers are responsible for creating an incredible amount of complexity.
A few tightly coupled comments around this complexity typically does nothing to help in the sustainability of the code.
Trust me, I’m not preaching from some holier-than-thou platform here. I look back on some of my past code and cringe. I do know that I write far fewer comments than I did in the past, but I feel that the work I do now is more sustainable than the code I wrote last year. And next year, I’ll probably look back on this year’s code and shudder. It’s a continual improvement process.
So what do you want to leave behind for the next developer who has to maintain your code? A big ball of mud? Or easy to read code with clear intentions? As someone who does a lot of maintenance coding, I’m sure you know my answer.
