Code comments as documentation?

Subject: Code comments as documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 29 Sep 2004 16:21:05 -0400


Joe Sokohl wondered: <<I'm working on a software design description. Developers are responsible for describing & documenting the software modules that make up the program. They've decided to use code comments (both header & inline) to make up the info that describes the modules. They extract the comments with a script to produce this doc.>>

Sounds great, but it's a completely misguided approach to producing documentation. The result of this is code-centered documentation rather than user-centered documentation: it defines how the software works, but not how people will use it. Think of the difference between a blueprint and a house and you'll get the idea.

That's not to say this approach won't produce a good source document that tells you how the code works--it can, if the developers can be forced to adequately document the code--which can be very useful indeed when you're documenting how something works.

<<This dynamic approach means the doc can be as up to date as the code is (assuming, of course, they edit their own comments whenever they make significant changes).>>

If this is the case, someone needs to take responsibility for confirming that the comments are comprehensible. The goal of commenting is to avoid the Adobe/Microsoft phenomenon: after 10 or 20 years of developing undocumented or inadequately documented spaghetti code, it becomes cheaper to throw out the application and start over from scratch. This is not a good thing.

This is what happened to PageMaker, and I'm told it's why Frame development was abandoned on the Mac. And as for Word? Blech. They haven't fixed the autonumbering bug and several key flaws in revision tracking (losing the reviewer's ID, for instance) after 10 years because nobody knows how.

<<My conern is in what to do with the doc I receive. Do I edit it to make the often obtuse and sometime grammatically incorrect developer-originating comments comprehensible, or do I let sleeping code comments lie?>>

If the goal of the comments is to communicate how the code works to the programmer who, 1000 years from now, is tasked with solving the Y3K problem, then you certainly need to dedicate someone to the task of creating comprehensive, comprehensible comments. If not, at some point the developers will have to throw out entire modules and rewrite them from scratch. (That's a strong argument you can make, but the way. Development managers hate to consider this.)

If the goal is to use the comments for documentation, you need a technical writer to turn "what this does" information into "how I use it" information. There's no reason you couldn't embed this documentation in the code, other than code bloat and the fact that it's a hideously inefficient way to create docs.

This is a complicated situation, since you need to have access to the actual code so you can maintain these comments. Developers often hate to let us touch the code or even see it, so that's a delicate political negotiation you have on your hands.

<<If I edit them, then they immediately differ from what's in the code.>>

Which is why you need to edit them directly in the code. Depending on the software development kit, you may be able to come up with a compromise. In Delphi, for example, labels are stored in an external "language" file, and are inserted into the program code only during compilation. As a result, when I worked for my previous employer, I was able to edit the interface directly in the language files, without ever touching the sacred code. The developers loved this approach. Could something similar work for your code documentation?

<<If I ask 'em to add the edited text back into their code, they do double work (and they're already frightfully resentful of having to do documentation of their code in the first place--this dev environment's rampant with the "just read the damn code" mentality).>>

Think of this as your opportunity to develop a way to take over a task they hate doing (documenting the code), thereby ensuring (i) that the job gets done right and (ii) that they end up deeply grateful that Mom and Dad Sokohl raised a technical writer. <g>

--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Previous by Author: Gui behavior issue. Need guidelines.
Next by Author: Re: "This page intentionally left blank" leaves me blank..
Previous by Thread: RE: Page numbering
Next by Thread: RE: Code comments as documentation?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads