Commenting Code (was Re: An interview question)

Subject: Commenting Code (was Re: An interview question)
From: phil stokes <philstokes03 -at- googlemail -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 31 Mar 2013 14:43:12 +0700

(I'll just preface this by repeating that my observation about Apple's poor
documentation was not about code commenting. Anyway, moving onâ.).

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.

I tend to use comments for debugging purposes, and remove them when I'm
done. Generally, I don't think any other coder is going to have problems
understanding my code, and if they do, they probably shouldn't be reading
itâ :D

On the other hand, comments are useful for scripts, where the intended user
is often someone who, it is assumed, does not understand the bulk of the
code but needs to modify certain parts of it for a particular task or
implementation.

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.




On 31 Mar 2013, at 06:09, Peter Neilson <neilson -at- windstream -dot- net> wrote:

On Sat, 30 Mar 2013 18:28:57 -0400, Keith Hood <klhra -at- yahoo -dot- com> wrote:

... That makes me wonder if Apple really pays attention to providing good
code comments.


There are two conflicting views about putting comments into code, even
though they do agree on the amount of commenting required:

1. "If it was hard to write, it should be hard to understand. Comments
should be omitted."

2. "The code should be so clear that no comments are necessary. Indeed,
comments generally tell what the programmer thought the code was doing, not
what it actually does. They are thus misleading and should be omitted."


Best

Phil
http://applehelpwriter.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?

Learn more: http://bit.ly/13xpg5n

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

Previous by Author: Re: An interview question
Next by Author: Re: Commenting Code (was Re: An interview question)
Previous by Thread: Making WebHelp topics findable
Next by Thread: Re: Commenting Code (was Re: An interview question)


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


Sponsored Ads