[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: Code comments as Documentation

Subject: Re: Code comments as Documentation
From: dmbrown -at- brown-inc -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 29 Sep 2004 13:28:29 -0700


Leigh Price wrote:

Personally, I'd let sleeping dogs lie. Here, those
kind of comments are not meant for public consumption.
I would consider myself a "view only" user of those
comments.

In fact, I don't usually edit code comments. Most often, I'm editing text strings that are actually part of the code. Occasionally I'll add or modify some logic, too, unless I feel it's outside my comfort range. :)

The only place I bother editing code comments is in files that are run through JavaDoc, which extracts developer documentation from specially formatted comment blocks. In that sense, the code files are really documentation source that just *happens* to include program code. Anyway, we create JavaDocs for only a small subset of our code base, the API used by developers who want to integrate the functions of our software into their own applications.

--David

=========================================================================

A V A I L A B L E N O W ! http://www.html-indexer.com

HTML Indexer is still the easiest way to create and maintain real indexes
for web sites, intranets, HTML Help, JavaHelp, and other HTML documents.





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

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.


References:
Re: Code comments as Documentation: From: Leigh Price

Previous by Author: Re: Code comments as Documentation
Next by Author: Re: ADMIN: Mail Header/Address Change (Message 1 of 2)
Previous by Thread: Re: Code comments as Documentation
Next by Thread: Re: Code comments as Documentation

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads