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.
(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?
