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.
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.
-Tony
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?
