Re: comments on comments on comments

[rickc@pogo.GPID.TEK.COM (Rick Clements)]

In article <2989@uvacs.cs.Virginia.EDU> you write:
>In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
>>What is needed to improve self-documentation are better programming languages.

>This is certainly true, but even the "better" programming languages allow for
>the inclusion of comments. There will probably always be parts of the 
>programmer's concept which need to be expressed in an informal way through
>comments.

I have learned to include comments like "Doing it <this_way> appeared obvious
at first but didn't work because of <something>".  I hate solving the same
problem twice (even if it a year or so later).  You can also list what trade
offs lead you to solve a problem the way you did.  The code can never tell
you the why.  Telling the person maintaining the code (maybe yourself) why
something was done will help them from creating those crash every 5th
Tuesday type of bugs.
----
Rick Clements (RickC@pogo.WV.TEK.COM)

-- 
Rick Clements (RickC@pogo.WV.TEK.COM)