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.
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
these!).
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?
