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

Subject: Re: Commenting Code (was Re: An interview question)
From: Nick Murray <flutable -at- hotmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 1 Apr 2013 19:28:00 +1100

Some more reasons for putting "why" comments in code:

Functions forming part of an API are usually "atomic" - they are fundamental steps that a piece of software takes in order for it to perform its function. API functions are usually named reasonably intuitively, and their internal documentation (parameters, limitations, results etc) are "reasonably" straightforward to document [as an aside, though, creating useful examples of API functions is not always easy].

However, the use of a particular API function, in a larger context or in a larger block of code, is not always intuitive. As an example, different functions in different versions of an API become deprecated, but there may be reasons for continuing to use the outdated function, for example, we use an older version of the .NET workflow API (3.5 I think) and yet the most recent version is 4.5.

This is where a "why" comment is necessary. It's not necessarily that the next person will be incompetent, but that the previous person has often spent considerable time in making the software behave as it should, and may wish to explain the "gotchas"to the next person.

Anyway in terms of stating a "best practice", I'd say this:
1. The code tells you how, the comments tell you why.
2. Use "why" comments when the line or block or function etc has been influenced/affected by software implementation or architectural constraints that are not "local" to the function or lines of code being commented.

On 1/04/2013 1:09 PM, phil stokes wrote:

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'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: Re: Need a collective noun
Next by Author: RE: Customized PDF with User Name
Previous by Thread: Re: Commenting Code (was Re: An interview question)
Next by Thread: Re: Commenting Code (was Re: An interview question)

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

Sponsored Ads