If you haven’t guessed, I like to write.
Some think I like to talk. No, not necessarily. But get me on the right topic, and I can go on.
Programmers are a funny bunch. They’ll write pages and pages of code, but they won’t say a whole lot. It tends to happen frequently with regards to comments.
Comments are blubs of text within code that don’t have much to do directly with the code, but tell us something about the code.
Comments help us understand.
Comments are also the subject of religious wars.
Some believe comments are evil and shouldn’t exist. I’ve seen a lot of course code that is devoid of comments. I generally assume the programmer is lazy or in a hurry when this happens. They might come back to say code should be self-documenting, but then I see the quality of their code is such that it doesn’t document much of anything.
To me, the trouble with self-documenting code is… what if the code is wrong? Comments (and perhaps design or API documentation written prior to the writing of code) provide a level of redundancy, because they provide the general overview, the abstract notion, the description of the promise of what is to happen. If the code jives, great. If it doesn’t, then we know there’s a problem. Can comments be wrong? Sure. But we tend to grok wrong comments better than wrong code, because it might be possible the code is right even if it looks wrong to us. What helps us determine that? You guessed it, comments.
See, comments are about the “why” of the code. We cannot tell WHY the code from the code; we cannot derive the reasons for the way the code is from the code itself. Once you write code, it will forever have to be maintained, so you need to think of the future maintainers — likely yourself 6 months from now, and yes you will have forgotten more than you expected. Do yourself a favor and comment your code.
I worked on a large software project many years ago. It was a huge beast of a mess of code. One day I went digging around after a memory problem and found a complete mess. See, every bit of memory you allocate, every resource you create, it must have a distinct owner. We have to know who made this mess so it can be cleaned up when we’re done. As I dug through the code, it became evident whomever wrote the original code played fast and loose with the ownership and numerous people assumed ownership over the memory but never rightly transferred that ownership. It created a massive mess, and in the end I determined there was no real safe way to properly clean things up. It was horrible.
Consequently, I wrote a lengthy diatribe in the code (comments) explaining the mess. It was pages long, because it was that ugly of a mess. I figured after all the crazy I went through, future folks ought to know about it so they could beware. Well… I left the company some months later, and then later on the product was sold to another company. I was at Apple’s WWDC (back in the old days) and came across a representative of the new company. When he saw my name his eyes got really wide and he said “YOU!!”. He started laughing. Seems they had come across my epic comment block and had a great laugh reading it, calling over everyone in the office to see it. He said I was a legend in their office for having written it. It was most amusing. 
What spurred this walk down memory lane?
Over at AltDev is an article The Elements of Comment Style. It talks about the value of comments and the different types of comments. I never gave much thought to the types of comments — it’s just comments, there to explain what code itself cannot explain. But the article provides good reason for comments, and links to writings of others, like Knuth and Raskin, as to why comments are good (and wouldn’t those guys know).
In all my years of programming I’ve gone back and forth and refined my approach to comments. Do I think we need to have copious levels of documentation? Well, sure that’d be nice and ideal, but it’s tough to do that because comments and documentation also have to be maintained. There isn’t always time. And that, depends upon the scope of the project. I’m sure if I was writing some system for the .gov I’d be documenting everything to the Nth degree. But working in the mobile app space, sometimes you have to move faster than is healthy and there isn’t always time for formal comments. Maybe the best I can do is a couple lines at the start of a function to give the basics of what it does then “self-document” what are legal parameters by having a lot of asserts of the parameters at the start of the function, which do provide documentation and also a level of code robustness. But that approach only works when we have full access to the code; writing an opaque library/SDK would require a different approach. So there’s always trade-offs and balances to be found, depending upon context.
I haven’t written a multi-page comment since that one.
And if nothing else?
A little humor buried in code can always brighten your day.
Filed under: Me, Programming Tagged: Me, Programming
