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 31 Mar 2013, at 21:50, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:
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.
I hear that Tony. I've been through it too, and indeed I still do with new
languages I pick up and some I've only toyed with on and off for years and
don't really use regularly enough to master. But like I said, that's
commenting for one's own learning benefit. Valuable, of course, as is
annotating one's lecture notes when studying at college. But I'm sure
you'll agree that for any language you use regularly and are proficient
with, they're a waste of time.
I don't see why professional coders (I'm not one; I'm still a hobbyist)
would or should bother with them. I don't use them for the three or four
languages I know well. For others, I use them less in inverse proportion to
my mastery of the syntax.
On 31 March 2013 21:50, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:
>
>
>
> 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
>
--
Phil Stokes
Language Instructor
Chulalongkorn University Language Institute
Phaya Thai Road, Patumwan
Bangkok, 10330
Thailand
Mobile: 0853349635
Technical Writing
Help Guides | Tutorials | User Manuals http://dl.dropbox.com/u/14906355/hiretech_write.htm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?
