Re: respect for the button slogan

Subject: Re: respect for the button slogan
From: Emily Berk <emily -at- armadillosoft -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 24 Aug 2001 12:22:31 -0700

On Thu, 23 Aug 2001 16:15:43 -0400, "Lin Sims" <linda -dot- sims -at- verizon -dot- net> wrote:
>The original version of this (I saw it YEARS ago at a science fiction
>conventions) is:
>
>Real programmers don't _comment_. If it was hard to write, it
>should be hard to understand.

Cute, but, in general, I've found that many programmers, including myself, do dutifully comment the parts of the code they think are trickiest. It's just that unsophisticated readers often need clarification about additional parts of the code. So I often either request that the programmer supply addition comments or write them myself. I'm not always successful in getting these additions stored in code, but usually if it's for a code example, I get my way.

I find that it is often the really inexperienced but very brightest programmers who resist commenting. Programmers who really know the score, comment clearly and often. I did get an email from a very intelligent but way young programmer recently mourning the molly-coddling of developers and the loss of the sense of mystery that thorough documentation caused. Sigh.

>...
>It's internal documentation, and just as important as end user
>documentation. I wonder if it's something any TW actually does
>(documenting the code, that is), although I know I haven't, nor have
>I met anyone who has.

When documenting Java, C and C++ APIs, I almost always include code examples, all of which are most useful, IMO, with embedded comments. If the code is furnished to me by a programmer and is commented, I edit the comments for grammar/spelling/clarity and run my proposed changes past the programmer, in hopes that my changes will make it back into the code examples stored with the API (and to make sure that I haven't changed the meaning of the comment.) If the code is not commented, I comment it and send it back for approval. If I am the one writing the code, I always comment the lines that I consider significant. (And, in the lead-in to the code text, provide an overview of what the code does and how it was designed.)

In Java APIs, the Java Docs incorporate the comments in the code and are often published to end users. I spend a lot of time reading the Java Docs and do send my observations and concerns about comments to the programmers. (And one of my concerns may be that a particular method is not commented clearly enough.) This is especially important when many of the programmers are non-native English speakers.

--Emily

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ Emily Berk ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc. ~
~ Project management, developer relations and ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: Change Happens (an incredibly long rant, sorry) was: Biggest salary cut you've taken?
Next by Author: RE: Questions about FAQs
Previous by Thread: Re: respect for the button slogan
Next by Thread: Re: respect for the button slogan


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


Sponsored Ads