I have to say that this is a noble desire, however K&R C rules state that
the names are unique only to 31 characters. If what you have to say
requires more, then you are stuck. When I developed a lot in COBOL it was
easier, now some tricks for bit manipulation require that you tell the
reader what the bit manipulation is for(and how it is done).

Kevin E. Dodd
Embedded Systems Consulting
2601 NE Jack London #49
Corvallis, Oregon, 97330
kevindod@cyberhighway.net
541.753.3633

On Tuesday, June 17, 1997 7:30 AM, myke predko [SMTP:myke@PASSPORT.CA]
wrote:
> Andy Warren wrote:
> >>     Just a 2cent comment here.  One of the best pieces of advice I
> >>     ever got about coding in a high-level language is, if you have
> >>     to put in comments, you're doing something wrong.
> >>
> >>     It means that your label (variable and function) names aren't
> >>     meaningful, you're code is needlessly complex and you're using
> >>     features of the language that aren't well known.
> >
> >and at least two or three people have already strenuously disagreed.
>
> Boy, that's putting it midly.  When the first notes came out, I went into
> hiding.  I got an e-mail from "knuckles@murder.com".
>
> >> I don't want to prolong the language debate overly long, but I CAN'T
> >> let this go by.  This is complete and utter bullshit, and I would
> >> never hire anyone who I heard suggest it in any but the most jocular
> >> terms.
> >
> >    Guys:
> >
> >    Before this gets completely out of hand and we start organizing
> >    a lynch mob or something, maybe we can find a way to rephrase
> >    Myke's advice in a way that lets us all agree.
>
> Thanx Andy (I came out of hiding when I saw this).
>
>
> I think when people read the original posting, everybody got so inflamed
> that they never seemed to get far enough down in the note to see the
paragraph:
>
> "This does NOT mean you don't document the code's requirements and
built-in
> arithmetic algorithms and assumptions; it just means that what the code
is
> doing should be evident to somebody after looking at it for just a few
> seconds."
>
> I guess I should have put this before the *really* imflammatory
statement.
>
>
> Andy Warren's discussion on what I was trying to say really hits the mark
> (and probably does it a lot more eloquently than I could have).
>
>
> The original statement about not requiring comments came from my fourth
year
> professor in operating systems at University.  When reviewing our code,
he
> literally took marks off for each and every comment that was in the "C"
> source code of the RTOS we had to write for the course.
>
> His point/perspective was that high-level languages are just that:
> LANGUAGES.  If you have to use another language (ie english) to explain
what
> you are doing, then you are simply not fluent in that language and if you
> are fluent in the language, then you should be able to express yourself
in
> that language simply and clearly.
>
> I agree that this point of view is extreme and not something that *I*
would
> code in exclusively.
>
> But, with this experience behind me, it does cause me to look back
> critically at my code and ask myself, is there another way to do this so
> that it is more obvious and easier to read when I have to fix it ten
years
> later?
>
> When I code I try to basically follow Andy's format: at the start of the
> code, I explain what the program/function is doing.  Within the code,
after
> I write each line, I ask myself is a comment necessary?  And, if it is,
then
> I look back and see if there's a better way to code the line.
>
> Sometimes there isn't and the comment is necessary.
>
>
> myke
>
> "If at first you don't succeed, then maybe sky diving isn't the sport for
> you" - Steve Smith