[Fwd: Re: Code comments as Documentation]

Subject: [Fwd: Re: Code comments as Documentation]
From: Steve Read <steve -at- readonly -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 29 Sep 2004 13:00:40 -0600


To further that thought, if they can write a script to suck comments out, perhaps they (or you) can modify it to shove them back in.

Steve

Why not make the text changes in the code yourself?

--- jsokohl -at- mac -dot- com wrote:

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 I edit them, then they immediately differ from what's in the code.
* 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).


=====
John Posada
Senior Technical Writer




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

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: Re: UK friendly?
Next by Author: Re: Asking for Author Credit In The Documentation?
Previous by Thread: Re: Code comments as Documentation
Next by Thread: Re: [Fwd: Re: Code comments as Documentation]


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


Sponsored Ads