Everyone that writes code has encountered or written their fair share of undocumented code.
A failure twice?
I was encouraged to write this article because of something I read about the pinball game that once was included with windows. According to the article on MSDN, the pinball game was removed due to a bug that should have been fixable. However, the overall qualify of the code made repair impossible and the game was removed from the distribution. Two major items can be taken from this:
- Failure 1: The could should have been self-documenting / few comments required.
- Failure 2: Code not easily understood should have been commented.
Properly commented code can be tricky!
In college they push you to comment your code while not stressing that over documentation is also bad. I remember writing programs that had comments on almost every line for assignments. In the end it doesn’t buy you anything, it just restates the obvious and clutters the solution. In the workplace, comments and whether or not the code needs them are hit and miss.
Some notes about comments:
- Many comments are an acknowledgement of your failure to communicate. Write better self-documenting code.
- Outdated or wrong comments are worse than no comments.
- Consider refactoring code that’s not self-documenting. I find one of the biggest places this can be done is extracting methods from if statements.
- Choose a good, descriptive names. I’m a little wordy in my names, but in the end most of my code can almost read like a sentence.
Remember
The code is your best documentation. Think about what you want to communicate with it and how to be as clear as possible.
