Comments as documentation Jun 29, 2004 11:46
There was a thread on delphi.non-tech last week about "Comments". It talked about when they should be used, their relationship to refactoring, etc.
Although not the point of this blog, I'll add my 2¢. In general, my opinion about comments is: they are a good thing if used sparingly. I typically don't comment my code a whole lot, but when I do, I like to think my comments are important to the comprehension of the code. I try to write my code so that I don't have to comment it. I also make an effort to refactor if something is unclear, rather than write a bunch of comments.
Ok, on to the main topic: Writing documentation using comments in code. AFAIK, this idea was first made popular in the Java world via JavaDoc. It has made its way into the Delphi community with guys like DIPasDoc and commercial tools like Doc-o-matic. In dotNet, the C# compiler has XML doc stuff built in and NDoc seems to be quite popular. For the rest of this blog, I'll simply call this concept "CodeDoc".
I think the idea of CodeDoc is a flawed one. If the majority of time spent within a development cycle is in maintenance and debugging, the code should be as readable as possible. I find that when I put comments throughout my code it clutters it completely. It's hard for me to read the actual code with all those comments and the "signal to noise" ratio of truly important comments goes way down. In some projects, I have been mandated to write these comments for property getter/setters; talk about noise! I write zombie comments like:
Very useful.
So what do I do in attempt to actually read real code? I adjust the IDE so that comments are the most subtle/quiet color in my editor; I try to ignore them the best I can. This is completely counter productive: if those comments are truly important for maintenance, then I've just ignored the message.
I don't think I'm alone, check out this JBuilder addon which is described as: "Option to fold/unfold all JavaDoc comments in a file would be even better as programmers usualy do not want to see JavaDoc comments when concentrating on writting code." Granted the author did say "writing code", but you get my point; I would have said "reading, maintaining and writing code; basically when you do anything involving code."
One can, and many do, argue for CodeDoc because of time spent in maintenance and debugging. Their reasoning is logical, well-documented code is easier to maintain. Well, yes I would agree. The problem here is that documentation must be maintained as well and typically, code is maintained before documentation is maintained.
Very often with bugs, what the code actually does is not the same as what the documentation of that code says it should do --- hence a bug. One can argue in the case of bugs, even if the code is wrong, the documentation still tells you what it should do which can help you fix the code. Indeed this is somewhat helpful, at least in theory.
The bottom line here is that I don't trust the documentation anyway. I'm not sure I know of any good programmer that does. I will concede that we are talking about degrees of trust here, but ultimately reading the code is what programmers need to do to debug the code. And isn't that what it's all about...writing, debugging and maintaining Code.
Well, perhaps I sound a little "old skool" here. I do believe that being a professional programmer involves more than just slinging code around and making software that does stuff. So let's look at the actual documentation that gets produced. NDoc produces nice stuff, like its Programmer's Reference. Many of the CodeDoc tools do something similar.
This is terrific. Honestly, as a programmer, I find a lot of value in this (although looking at the code is still better). But just how many programmers are writing software for other programmers? Many do, but I suspect most don't.
I write software for regular office people, some technically savvy, others not so savvy. Documentation like this is worthless to them, they want a User Guide and a regular Help file. Things that a classic word processor or apps like Help & Manual can produce. Writing a user manual is just not very sexy is it? Much cooler to spit out a bunch of documentation from code automatically, right? Not really; not if your users are regular folks.
So will I use CodeDoc tools? Maybe, but only if I'm producing software for programmers and even then unlikely.
I haven't used dotNET's version, and it looks like it's much better with <include>. What I want, and perhaps this already exists, is something to read my code, export stubs in XML, handle the diffs caused by refactoring intelligently and let me fill in my comments using a text editor. IOW, keep my code documentation out of my code!
Here's a haiku:
like fog cannot read clearly
user guide still blank
Write a comment
- Required fields are marked with *.