Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.programming > #1979

Re: self-documenting code? a pipe dream?

Show all headers | View raw

On 7/18/12 12:05 PM, malcolm.mclean5@btinternet.com wrote:
> בתאריך יום רביעי, 18 ביולי 2012 19:18:28 UTC+1, מאת bob:
>> Is anyone still trying to write self-documenting code that people just automatically know how to use?
>>
>> Or is this largely a failed concept?
Self-documenting code doesn't mean someone will automatically know how 
to use it, but will understand what's going on when it is being used. 
Self-documenting code is muck more useful on read than write, though it 
is still helpful.
>>
>> I remember hearing people wanted to do this with Java.  Then Sun kept releasing all these tutorials and what not for stuff that was supposedly self-documenting.
>>
> Some studies have shown that comments make code harder to read and to understand.#
I'd be interested in seeing the studies you mention. Can you cite real 
studies, or are you making that up?  Anecdotally, I find bad comments to 
be worse than no comments, and well-placed and well-worded comments to 
be the most helpful.
>
> Java had a sort of defined format comment system, which would the generate documentation.
Called JavaDoc. I've seen similar things in C/C++ (I believe Doxygen is 
one such product).

> The problem is that where several components work together, it's not too useful to have a list of the properties of each one. What the calling programmer needs is an example of how to use the components to perform common tasks.
>

The problem is that there are many different kinds of comments and 
documentation, and schools don't tend to teach what the differences are, 
or when to use each one.  New graduates end up commenting their code in 
ways that make sense only from a homework point of view.
"// assign 'a' to 'b'".  Bletch.

For line comments:  Don't tell me *what* the line does (unless it is 
particularly complex). Tell me *why* it does it.

For function/method documentation: Don't tell me *how* a function/method 
does its task (unless that's material), but tell me when, why, and how 
it should be called.

For class/module documentation: Tell me what the class or module is 
useful for, and *give me examples*!  Point to Unit Tests, which should 
be real-life documentation on how it is used.

Back to comp.programming | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

self-documenting code?  a pipe dream? bob <bob@coolfone.comze.com> - 2012-07-18 11:18 -0700
  Re: self-documenting code?  a pipe dream? malcolm.mclean5@btinternet.com - 2012-07-18 12:05 -0700
    Re: self-documenting code?  a pipe dream? Daniel Pitts <newsgroup.nospam@virtualinfinity.net> - 2012-07-18 12:50 -0700
  Re: self-documenting code? a pipe dream? Aaron W. Hsu <arcfide@sacrideo.us> - 2012-07-18 19:24 -0500
    Re: self-documenting code? a pipe dream? Nick Keighley <nick_keighley_nospam@hotmail.com> - 2012-07-19 01:21 -0700
      Re: self-documenting code? a pipe dream? Aaron W. Hsu <arcfide@sacrideo.us> - 2012-07-19 16:07 -0500

csiph-web