Re: Encouraging good comments Which language ?

[Steve Litt <slitt@...>]

On Sunday, January 29, 2012 07:57:42 PM YES NOPE9 wrote:
> If this question has been addressed previously.... please point me
> in the correct direction.
> 
> What language is most likely to encourage good commenting ( What is
> being done and why ? )  and make the code easier to support by a
> future maintainer  ? Or is this just not something that is
> influenced by the language......
> 
> 99guspuppet           99comments

Hi YES NOPE9,

First I'll answer the exact question you asked: I think Fortran or 
Assembler or DBASE II would most encourage good commenting because 
they have no hope of being self-documenting. That's also a part of why 
they're not used much anymore.

Now I'll expound on questions you did not ask :-)

I'm a big believer in self-documenting code. So if I have a subroutine 
that writes one record, you'd better believe I'll call it 
write_one_record(). If I have a collection and write a method that to 
append a new element to an existing one, I'll call the method 
append(). If I have a loop over 8 lines long, I'll call the loop 
variable records_read, not i. If a table keeps track of the various 
attributes of a person, I'll probably call it person or person_record. 
A table that's for practical purposes an array of persons I'd call 
people. These are things I do in every language.

Beyond those things, I think it's vitally important for the original 
programmer to make clear his design intent, so that those who follow 
him can cleanly add on to his design, rather than using duct tape to 
shoehorn new stuff onto it, or change part of the design and leave 
part of it the same. How many times do you see two or three variables 
that do basically the same thing, added at different times by 
different programmers. That happened because the design wasn't clear.

I'm a big fan of a separate design document with diagrams. Takes a 
half hour to read and saves a week of kludging. Also, for the same 
reason, I favor comments before every class, method and subroutine. 
Number one, it takes less than five minutes per comment, and if the 
original programmer can't afford that, well... Second, those comments 
make it clear at a glance where new things start, and that's very 
handy for the maintenance programmer.

Last but not least, a few people said this thread is offtopic. I've 
maintained code written by people who thought commenting was offtopic, 
and believe me, their code proved it was very much ontopic. The 
programmer who refuses to comment, whether in Lua, Python, Cobol or 
Bash, is forcing those who follow him to get lost in backwater swamps, 
and make new swamps to make it right.

SteveT

* My new 99 cent Kindle book  :  http://www.amazon.com/dp/B006QTBLA2 *
*                 Steve Litt  :  http://www.troubleshooters.com      *

.