--- On Mon, 10/6/08, Olin Lathrop <olin_piclist@embedinc.com> wrote:

> From: Olin Lathrop <olin_piclist@embedinc.com>
> Subject: Re: [EE] Self documenting code vs. Comments
> To: "Microcontroller discussion list - Public." <piclist@MIT.EDU>
> Date: Monday, October 6, 2008, 4:50 PM
> 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.
> 
> -- 


  Books can state a world on comments but it has to end somewhere.
If I was to comment my entire code it would not be effective. It is
a blend of code and comments when the intention is not clear. I than
to write better comments when I keep the projects for a long time. Still
does it make sense to heavily comment on a project you will throw or delete
after a week working on it?

John




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