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: phil stokes <philstokes03 -at- googlemail -dot- com>
Date: Mon, 1 Apr 2013 10:27:35 +1100

Phil, the comments expressing the "why" ("why this code is here")
explain the purpose of a function or functions, or extra lines of code,
in the larger context of what the system does.
The "how", as expressed in the code, means "how the intents of the
software developer/programmer are expressed in code so as to make the
system fulful the function or behaviour for which it is intended".
There may be constraints on the software implementation (response time,
requirement to interact with legacy software or systems, hardware
limitations and so on) that require the developer to include
not-immediately-obvious code.
A good example is synchronising with Apple's iCloud service, which
apparently works well in some situations but not well in others. In
this example, there would be code that "saves my document", which would
be reasonably obvious to anyone developing in the Apple ecosystem.
However, there might also be code that uploads a small,
randomly-generated document to iCloud to test response times, and if
the response time is long, displays a message to the user warning about
network congestion or whatever. This "test" code might have a comment
such as "upload random doc to test response times". (Whether or not
this is good software design is another story).
The purpose of the surrounding or supporting code is therefore to work
around, or support, the "boundary" or "edge" or not-immediately-obvious
situations that most software has to deal with. It might also be a
quick hack (due to time or money constraints. I've seen a few of
This is why there is, in some situations, a need for comments
explaining "why" certain code is present. It doesn't have to be long,
convoluted and hard to maintain, it could simply be a reference to an
issue in a bug-tracking system ("Jira issue XX-3453 test network
response times before uploading large docs to iCloud") or a couple of
words that elaborate on the design decisions made. Even when you code
against international standards (I work in the geospatial field,
there's ISO standards everywhere), you occasionally need to elaborate
on something you've done or mention *which* version of a standard you
are coding against eg ISO 12344 draft 3.
This tells anyone reading the code that you've had to code against a
draft standard, and your will probably need to be updated once the
final version of the standard is released.
Does this make sense?
On 1/04/2013 3:20 AM, phil stokes wrote:

I'm interested in that perspective, Nick, but could you elaborate?
Surely the only 'why' is that each function, struct, array or whatever
is necessary for the application or process to function.
>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 @


Commenting Code (was Re: An interview question): From: phil stokes
Re: Commenting Code (was Re: An interview question): From: Nick Murray
Re: Commenting Code (was Re: An interview question): From: phil stokes

Previous by Author: Re: Commenting Code (was Re: An interview question)
Next by Author: Form application for Tablets
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