RussellMc wrote:
> Nah. That's not brave. Just trolling :-).

No Russell, I'm not trolling. Honest.


> - He's loaded for Ol.. er, Bear. "Some people" advocate commenting in
> a style that could be adumbrated to be criticised  heavily by such a
> remark, and they might be expected to come running. Might. (I probably
> comment code at about the level tat Olin advocates, but, that's
> another story.)

Consider the possibility that we are both right. Olin's tool of choice is 
assembler. The scope of my comment was limited to C.


> - How many people have you EVER had to ask to document their code LESS.

Someone actually told me more than once that I documented my code too much, 
and that comments impeded his understanding of the code. This was before the 
truth was revealed to me.


> - How many of the many many many papers etc written on good
> programming that you have met have recommended reducing documentation?

How many books teach waterfall as a valid project development methodology? 
Why do both feel so unnatural?

The trend is changing. Our desktop brethren already embraced agile 
methodologies, which advocate exactly what sounds so ridiculous to you: LESS 
documentation.


> - How many listings have you read where you wished there were LESS
> comments. (And how many where you wished there were more?).

I don't recall wishing for either, anytime recently. I do recall thinking 
many times, "this code can use some serious refactoring".


> - If you read your OWN code after 1/6/60 months do you tend to wish
> for more or less comments.

It hasn't been 60 months since we adopted the methodology. But I can easily 
find my way around in code I wrote 1.5 years ago, and in my partner's code.


> - Short of a major problem, how many people are going to write comment
> material in detail BECAUSE their code is poor. The implication is that
> the documentation is perceived to be needed to make the code work
> better (hasn't worked from Ada on), or to make people THINK your code
> is good (some may look at documentation as primary evidence - most
> just run the code first and see what it does.

You don't have to go far. Look at Microchip's 18F library. It's a 
wonderfully documented mess of a code.


> - Would you buy a good low mileage only driven by a little old
> man/woman on Sunday's horse/car/other from someone who advocated less
> or lower levels of or minimal commenting?

Sorry, I don't understand your metaphors.


> There are, arguably, 5 levels of comments or related documentation levels.
>
> Project description. Sets the stage
>
> Per module or block or ...
> ALL modules blocks will have SOME comments.
> Usually will describe functionality.
> Usually will list variables/parameters and may and describe them
> unless well established at higher level.
>
> Per paragraph of code - 1 to some lines. Commonly (1<= Some <= 10),
> maybe 10-20, seldom > 20 depending on level of language and type of
> routine. eg N lines of identical inline shifting, fall through  NOP
> stacks for isochronous timing adjustment etc will merit less comment.
> All 'paragraphs' will have some form of comment
>
> End of line or equivalent. Many or most lines will have such.

Texbook style, followed it faithfully for years. Description for the module, 
function block describing function purpose and parameters.

Nowadays have maybe one comment per 100 lines of code, only where necessary. 
Why? The magic of "loose coupling, tight cohesion". The module name 
describes its purpose. The header file contains all the access functions (a 
small number, because public functions are the enemy of loose coupling). 
Each function does exactly what its name says. Same goes for parameters.


> Variable/label/function/subroutine/ ... / names - self documenting.
>
> No?

Yes, but I suspect we would disagree on the definition of "self 
documenting". Most people's code isn't self documenting enough, hence the 
need for copious amounts of commenting.

Vitaliy 

-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist