Re: Code comments as documentation?

Subject: Re: Code comments as documentation?
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 30 Sep 2004 09:11:07 -0700


Quoting TechComm Dood <techcommdood -at- gmail -dot- com>:

> Wrapping in documentation at the source code level requires a slightly
> different practice, but the fundamentals are all the same. This
> practice is no more hideously inefficient than any other practice,
> it's just different.

Good point. And to add to it:

- Given that you're dealing with plain text files, the concern about bloated
code seems misplaced. In this day of multi-megabyte executables, you'd have to
include tens of thousands of words to increase the size appreciably.

- The insistence on separating documentation from code seems likely to
perpetuate divisions between writers and programmers. There's nothing special
about documentation. It's just another part of a product. If anything, including
documentation in the code tends to make both writers and programmers remember
that they are working together on a common project - an attitude that tends to
improve both documentation and code.


> I also have issues with the blanket assumption that developers hate to
> document/comment their code. I've met some that dislike to do it, and
> I've met others that deem it a critical aspect of their profession.

It also depends on company policy. At some places I've worked, programmers have
had a style guide defining such things as tabs, when they are used, and how and
when code is commented.

--
Bruce Byfield

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

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.



Follow-Ups:

References:
RE: Code comments as documentation?: From: France Baril
Re: Code comments as documentation?: From: TechComm Dood

Previous by Author: RE: Code comments as documentation?
Next by Author: Re: Code comments as documentation?
Previous by Thread: Re: Code comments as documentation?
Next by Thread: Re: Code comments as documentation?


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


Sponsored Ads