TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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?
snip
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.
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
