Vitaliy wrote:
> - Good names eliminate the need for line-by-line comments

I think this is our major disagreement.  A good subroutine name, for
example, can at best explain what the subroutine does.  Only a comment can
explain why that function is being used right here right now.

> Comments are passive --
> you use them to describe what a function does, often after you've
> already written it.

No!  Header comments describing a subroutine must be written first, then the
subroutine written.  You can't implement something until you've designed it.
The comments put down in writing the design of the interface to the
subroutine.  The header comments are sometimes useful to refer back to
during coding since they are the spec.

Of course you can change your mind as you get into the implementation and
update the comments accordingly.  Sometimes you encounter issues in
implementation that you didn't consider when you designed the subroutine
interface.  You have to be flexible enough to allow the subroutine to be
redefined as makes sense within the overall system.

> This goes agains the principle of loose coupling. The function should
> only be responsible for itself. It has no business knowing anything
> about the function(s) that are calling it, or what they're doing with
> the return value.

I was referring to comments by the call, not the subroutine definition.
Even if the subroutine name explains exactly what it does, it can't explain
why you are doing that particular thing right here now.

> That's actually an excellent argument for not commenting every line.
> Use the space you would otherwise waste on comments, to create a
> descriptive function name. Make it as long as necessary. If the name
> is too long, it will tell you that the function is doing too many
> things, and needs to be broken down into smaller, more cohesive
> functions.

But then where do you describe the why as apposed to the what of the
subroutine call.

> Why?! Characters in symbol names are *free*. Your suggestion goes
> against the recommendations of leading programmers, and common sense.

Horizontal space on a line is limited.  Everybody's window has some max
width, and long lines get cumbersome to handle.  Therefore characters used
in one part of the line take away from possible use in other places.
Comments perform a important function that can't be replaced by any amount
of clever naming, and therefore have their purpose on most lines.  You need
to ballance explaining the what with the why.  Clever names can only tell
you the what at best.

> Make the function name more vague -- to save three letters?

My point was that actually no information is lost.

>> The bad part
>> about these two lines is that the comment was omitted.  That is a
>> wasted opportunity to explain the next level up what the function is
>> about or what
>> the forward voltage is or why you'd want to get it right there.
>
> So, change the function name to say exactly what it does. Put the
> comment inside the function name, and you won't have to remember to
> copy/paste the comment everywhere you use it.

Again, the function can only explain what it does, not how and why it is
being used in a particular instance.

>>  if (ForwardVoltage() > 100) {  //finally reached minimum level ?
>>
>> or
>>
>>  if (ForwardVoltage() > 100) {  //above safe operating limit ?
>
> Unfortunately, neither comment makes sense in the context of the
> application:

It was just a example I made up.  I wasn't suggesting this code for any
particular application.

>     if ( FinallyReachedMinimumLevel() )
>         LightMinimumLevelLed()
>
> or
>
>     if ( IsAboveSafeOperatingLimit(ForwardVoltage) )
>         SoundCriticalAlarm();

But shouldn't that be:

  LightMinimumLevelLedWhenFinallyReachedMinimumLevel ();

  SoundCriticalAlarmIfAboveSaveOperatingLimit ();

Where does this end?  At some point you have to write some real code.

Nested levels of abstraction is a fundamental concept of software, but it
can be carried too far just like any good idea.  In my opinion, you're off
the deep end with this.

Vitaliy, I know you're a smart guy, but I think you've read too many books
and papers by ivory tower computer science types that have forgotten (or
maybe never knew) what it was like to get real projects done.  All these
high-fallooten concepts have their applications in various places, but
should all be taken with some salt and they aren't the cure-all they each
claim to be.  Just because someone came up with a better way of doing
something in the narrow niche they tested and wrote a book about it, doesn't
mean it should be blindly adopted in all other cases.  Read the book, gather
the ideas, but then let some reality set in to decide when and if to use
them.

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