A few years ago, I was interviewing candidates for a systems analyst job, and trotted out one of my standard questions: Tell me something you have done that you are proud of. This particular developer called out her source code annotations (comments), and was rather specific about her own comment quality standards. But when I asked her if she likes to write documentation, she was quite hesitant – and that surprised me a bit, made me think.
What’s the difference between writing documentation and code comments?
- Comments let you walk away: Well-formed comments and a consistent style make your code readable – and maintainable. Forward-thinking coders should invest the time now, so they will not be stuck in the future as the only person who can maintain the code.
- Documentation speaks over time: A complete set of documentation let you pass on ownership (pwnership?) of an idea, a task, a process – allowing you to impact actions and thought over time and space (a hefty virtual lever).
At first, there seems to be a clear difference – good comments are almost always selfish (please don’t bug me with this old stuff, I’m doing something much cooler these days …), trying to avoid future work. On the other hand, good documentation can be driven by ambition (if anyone can read the manual, more people can use this stuff without me holding their hand …), hoping to leverage a chunk of work over multiple people.
I could make a case that code comments are a form of documentation, and are altruistic (respect for the coders that will follow in your keystrokes). In the end, I believe the root issue is this: comments are just another form of code, read by a select few people that are probably just as bad at documentation as you are, while documents are expected to be readable by a larger number of reasonably educated people who are nevertheless not as technical as you.
Can a Good Commenter become a Good Documenter?
Still, some folks see the value of effective communication, and would like to translate their structured, short-form writing skills to the broadly distributed world of emails, FAQs, and Project Charters. Are these talents transferable?
Think about your (now strongly developed) opinions on what passes for “good” code comments. Most of the time, these opinions / expectations are built by bruising your knuckles when maintaining other people’s code …
I wish they had indented the code like this … or at least done it consistently …
If only they had documented what they were trying to do in this function header, I’d know where to start debugging …
These variable / constant names mean nothing – thank goodness for multi-file search and replace …
So, why not apply that same mentality to documents? You know what you like when you read it – what works and what doesn’t. When you are done reading a chunk of text for the content, ponder a moment on how it was constructed. Think about what worked for you – how the author arranged the words in such a way that you came away with comprehension, maybe even excitement and energy. Find an author style that you like? Then shamelessly copy, and make it part of your own style.
This Post Has 0 Comments