To comment or not to comment...

by Scosby Thursday, February 12, 2009

After recently being told, "you comment your code too much", I was shocked. I quickly explained my intent was to facilitate documentation of the code, and not for consumability, should we ever desire to produce such luxuries. This seemed to barely be an acceptable response, so I took to the internets.

In my humble opinion, if you're such an elitist programmer that you don't need comments to read code, then you're perfectly capable of taking your own advice and can ignore them in the source file as if they didn't exist -after all, this is what managed compliers do anyways. Apparently, I am not one of the chosen few who are able to compile and excute code statements in their brain. However, I have been "that junior developer" who has had to maintain code from a cowboy who considered himself an elitist that wrote perfect, self-documenting code...he most certainly did not write anything close to this kind of coding pattern, and I wanted to pull my hair out after going through 10,000 lines of undocumented code that mostly didn't work. So please, do us "lesser" developers a favor and save us from having to jump all over your custom APIs and frameworks to see what the implementations are doing by putting some comments in there. I promise, you'll spend less time ignoring comments in code than answering questions from the "juniors"...that is if you work with people confidient enough (or ballsy?) to ask you questions, b.c. you're a code troll anyways.

Utimately, I admit that not everything needs commenting because one probably doesn't publish the entire source in documentation anyways. But I tend to be verbose and GhostDoc (free, btw) makes it sooooo easy to comment in Visual Studio that I have a hard time not doing so Laughing

I found Dan Dyer's blog post to be representative of what I agreed with on the internet. Thanks, Dan.


Tags: ,

Technology | Programming