Re: Commenting Code (was Re: An interview question)

Subject: Re: Commenting Code (was Re: An interview question)
From: Keith Hood <klhra -at- yahoo -dot- com>
To: phil stokes <philstokes03 -at- googlemail -dot- com>
Date: Mon, 1 Apr 2013 01:04:16 -0700 (PDT)

As I see it, the question of the possible replacement's competence or lack of it is irrelevant.  As tech writers, our job is to make things clear for other people. It's not a matter of trying to lessen the impact of the employers' bad hiring decisions, it's a matter of doing a job.

Assuming the time is available...If we have the opportunity to do it, putting comments in code is just doing our jobs.  If the programmers are the ones who would do any commenting, I can't think of a good reason why they shouldn't. 

I think the best reason for commenting code is the fact that code must be maintained throughout the full life cycle of the product.  To be maintained efficiently, it has to be understandable.  Comments can make it easier to understand.  That makes the code easier to maintain.


From: phil stokes <philstokes03 -at- googlemail -dot- com>
To: Keith Hood <klhra -at- yahoo -dot- com>
Cc: Tony Chung <tonyc -at- tonychung -dot- ca>; "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Sunday, March 31, 2013 9:09 PM
Subject: Re: Commenting Code (was Re: An interview question)

On 1 April 2013 08:49, Keith Hood <klhra -at- yahoo -dot- com> wrote:

But when you get run over by a bus and your job is taken by a guy with only half your experience, that guy will need help.  

I find this way of putting it unconvincing. Do we have an ethical obligation - and is it ethical to spend our employers time now - engaging on activities to ameliorate the possibility that our employers will hire someone incompetent in the future? 

I suppose this is a species of the larger argument about whether we should document our working practices in general for future project owners. I know that argument has been had on this list before, and I don't particularly want to get it into it here (my view on that is its situation specific). 

I'm more interested in what's the BEST argument for commenting code or recommending commenting as 'best practice'. Thus far, I think Nick's given some good reasons, but I'd be interested to hear more arguments, for or against.
>From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: RE: Viewing WebHelp in IE9 Creates Two Vertical Scroll Bars
Next by Author: Working with developers (was Re: About The Cloud: Quick-Read Suggestions)
Next by Thread: Re: Commenting Code (was Re: An interview question)

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

Sponsored Ads