[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: John Bartol <johnbartol -at- jaggedpeak -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 30 Sep 2004 09:30:41 -0700


On Thu, 30 Sep 2004 09:11:07 -0700, Bruce Byfield <bbyfield -at- axionet -dot- com> wrote:

- 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.

Actually, in a compiled system, the comments are ignored in the compilation of the executable code. That is, a "hello world" program consisting of 5 lines of code
will result, when compiled, in an executable binary that is *the same size* as
the same program with 2000 lines of comments. So... no effect on size at all.


- 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.

This is something I am going to be trying to convey to a client of mine (for whom I worked as a programmer for many years). I am in the process of using Doxygen to prepare some sample API documentation for them, and am going to try to convince them of the value of having adequately commented 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.

It's definitely a mixed bag that depends on the existing code base, timelines, project management style, staff composition (salaried/contract), etc., etc., etc. In my experience, most developers will agree that good commenting is important, but when faced with tight deadlines, will sacrifice the time needed to document *for the future* in favour of completing *for the present*.


--
John Bartol
Jagged Peak Technical Communications


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

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
Re: Code comments as documentation?: From: Bruce Byfield

Previous by Author: RE: Every good story must have a SQL
Next by Author: Technical scriptwriting advice needed
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