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

Subject: Re: Commenting Code (was Re: An interview question)
From: Tony Chung <tonyc -at- tonychung -dot- ca>
To: phil stokes <philstokes03 -at- googlemail -dot- com>
Date: Sun, 31 Mar 2013 07:50:50 -0700

On Sun, Mar 31, 2013 at 12:43 AM, phil stokes
<philstokes03 -at- googlemail -dot- com>wrote:

> (I'll just preface this by repeating that my observation about Apple's poor
> documentation was not about code commenting. Anyway, moving on….).
I caught that. But you know technical writers think they know
everything--they don't need to actually READ anymore. ON the chat list we
refer to that as "Reading Comprehension Disorder".

I have some sympathy with the 'no comments' philosophy in coding. A good
> programmer can read the code anyway, and comments just get in the way. If
> you learned C with 'The C Puzzle Book' as I did, you come to love reading
> well-written code natively and find comments an annoying distraction. Also,
> as I think someone else here has said, programmer comments are not always
> accurate and can in fact be misleading.
Which would be an excellent segue into the idea that a writer well-versed
in code could actually write useful code comments, which could then be
extracted into end-user API documentation, or just reference material.

> I've never much bought into the 'you wont remember what you were doing a
> year later' argument for commenting, unless you don't use that particular
> language regularly enough to be able to read it fluently or are just
> learning it.

As a primarily self-taught developer I can attest to how my code
style/methodology changes over time. Maybe not one year later, but two or
three years later. I look at some of the code I wrote way back in the day
and wonder how I got there. If not for comments... Heck, even something
simple like "Function reads these values and returns this object array" or
something would be helpful. Saves a lot of time reading code that could be
better spent playing with the kids.

But I guess more disciplined coders are able to understand their
chickenscratches a whole lot better. I think my style has improved with
age, and I'm beginning to use common patterns that anyone could understand.
But before, when I only programmed PHP, I found that you could get away
with ANYTHING, so I tried.

>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

Previous by Author: Re: Who is an ESL writer?
Next by Author: Re: The great note-taking divide is coming
Previous by Thread: 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