I stumbled upon an interesting article titled: Comments Are More Important Than Code. In this article, the author, Jef Raskin, writes:
Good documentation should be readable on its own, with bits of code showing how the design is implemented (and making it run, of course). Reconstructing code from good documentation is far easier than trying to create documentation given the code.
The essential concept of writing the documentation first, creating the methods in natural language, and describing the thinking behind them is a key to high-quality commercial programming.
Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain’t so.
This reminds me of a post I wrote about a year ago: Comments Do Make a Difference. It was about a real world experience with code that was not adequately documented. I believe that good code should be self-documenting. But, I also agree with Jef that “good documentation includes background and decision information that cannot be derived from the code” no matter if it is self-documenting or not.
Possibly related:
- Top 10 Ways to Know Your Software Project is Doomed
- CURRVAL and NEXTVAL
- Google Code Search is Live
- 10 Programming Quotes and Lessons Learned
- Comments Do Make a Difference
Tagged | Post a Comment
Hope everything is working out...
Hey Eddie
August 24th, 2007, at 9:51 am #As someone that regularly takes code from developers and write technical docs on top of them I completely agree on the importance of comments. Our product is v java biased so we get javadoc but thats not guarantee of good comments :o)
Tim
Thanks Tim for confirming the importance of comments, even if you have javadoc. Have a great weekend.
August 24th, 2007, at 4:27 pm #Oh boy, I can only agree with 110%.
Okay, there are definitely some very small program units that don’t need any explanation, but….
Often I discover some hellish program unit (read: large), that looks beautiful, but no comments. Questions like where did the original coder intend the routine to be called from, what business requirements was it trying to hit, what are the preconditions and postconditions on the unit running, are there any hacks in the code to get around bugs or unusual situations, if a workaround for a database issue — what version of the database did the bug occur in ….. and so on.
“Just” readable code without any comments just doesn’t convey this sort of information.
The fact of the matter is most developers don’t like writing documentation, they’re too lazy, and this is another reason developers as a group get a bad wrap.
I think a lot of developers who took the whole readable code band wagon on board, took it outside of the context that you need to comment when commenting is necessary. They are both useful techniques.
Phew! So much pent up rage for a Saturday morning
Cheers,
CM.
August 24th, 2007, at 5:23 pm #Could not agree more Chris. Enjoy your weekend.
August 24th, 2007, at 9:23 pm #Hi,
i think it’s a question of the scope; You need documenation outside of the code to get the whole picture and to be able to deliver your business rules/requirements to others.
In more detail the commented code tells you how the aspects of the Business requirements are implemented. Two different focus of ducumentation.
Karl Reitschuster
August 30th, 2007, at 11:18 pm #Good points Karl. I would kill myself if I was required to add the 100 page business requirements document to my code. However, I would at least point to it or describe briefly why I’m coding this logic this way versus that way.
August 31st, 2007, at 5:12 pm #Right on!
I believe there’s no such thing as ’self documenting code’, for several reasons.
I will name one: The code can only tell you what it is doing. Not what should have been done.
That means that if the code has a bug, there’s no way you are going to find it by reading it!
Let’s take a trivial example:
for (i = lstItems.count; i >=0; i–)
{
..
}
Well, is this code right? Wrong?
Who knows…
There’s no programmer, in his right mind, that will dare to touch this code if it was already in production.
S/he may suspect this code is ‘broken’ but s/he cannot know for sure, so it will stay that way until it crushes (or forever).
Now say there was this line of documentation before the code:
// Loop over the Items list backwards.
So, is the code buggy? Sure it is!
And this is for a very trivial example. Once you get into more complicated scenarios, comments become all the more important.
December 14th, 2007, at 1:49 am #Mulick, I like your line “The code can only tell you what it is doing. Not what should have been done.” very true. Your example illustrates your point very well.
December 14th, 2007, at 8:22 am #