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

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

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.

Best

Phil
http://applehelpwriter.com



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?

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:

References:
Commenting Code (was Re: An interview question): From: phil stokes
Re: Commenting Code (was Re: An interview question): From: Tony Chung

Previous by Author: Commenting Code (was Re: An interview question)
Next by Author: Re: Commenting Code (was Re: An interview question)
Previous by Thread: Re: 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