Thanks for your replay. Next time when I go to book store
I will definitely get the book you are recommending.
Now I have more question about same routine since "cases"
Do not work I changed them to "if" that is what you
Guys are recommended now I have another problem that I do not
Get it. In if statement when I change "adj" to 0 or any
Value ADC and timer1 start working and when I put
If(count==(28+adj)) adc and timer1 do not work at all.
I checked count variable with break points and watch
Window looks ok this is strange when I do this on count 28
And count 30 it works but when I continue doing it on all of them
Adc and timer1 do not work any idea?

>
> In your HI_ISR code (24 lines of C code) I found
> *one* single line comment, this one:
>
>
> CLRWDT(); // clear WDT
>
>
> Couldn't have said it better myself ! :-) :-)
>
That reminds me of a story from one of my old EE profs. She inherited a
project that has something like 20,000 lines of assembler, and there was
one single comment, about halfway down the program. The comment was
"Yes!"

>
> Alex,
>
> I do not think any body can write 20,000 line of code
> Without any comment. 20,000 line assembly code is too much
> To remember maybe it was 20 line. :-)
>
I agree with you. It doesn't seem possible to me, either, but it wasn't
my story. :-)

However, I could see someone writing 20,000 lines of code in a
high-level language like C++ or Java without comments. If you have good
variable and class names, you could probably get by and have a small
chance of being able to maintain it. (so-called "self-documenting" code.
It's not a good idea, by any means, but it would be possible.

Alex Kilpatrick wrote:
> However, I could see someone writing 20,000 lines of code
> in a high-level language like C++ or Java without comments.
> If you have good variable and class names, you could probably
> get by and have a small chance of being able to maintain
> it. (so-called "self-documenting" code.
> It's not a good idea, by any means, but it would be possibble.

I did it in VB6. (proper architecture of a solution,
well-structured code, meaningful variable, class and subs names)

Commenting does not help much if the developer is to maintain
an application. Choosing wrong architecture could turn
developers life into nightmare.

Mike Singer wrote:
>> However, I could see someone writing 20,000 lines of code
>> in a high-level language like C++ or Java without comments.
>> If you have good variable and class names, you could probably
>> get by and have a small chance of being able to maintain
>> it. (so-called "self-documenting" code.
>> It's not a good idea, by any means, but it would be possibble.
>
> I did it in VB6. (proper architecture of a solution,
> well-structured code, meaningful variable, class and subs names)

But WHY?!!

There is no such thing as self-documenting code. Useful symbol names
provide quick hints to what the symbols are about, but they don't substitute
for a real explanation. Not by a long shot. And, they don't help much in
documenting the bigger picture. They are just one piece of a much larger
solution.

>
>Commenting does not help much if the developer is to maintain
>an application.

I have to disagree on this point. It is only true (and then only to a
limited extent) for a program that's undergoing active development.
Over time, many of the things that are readily apparent to you now
will become vague recollections of your orginal thinking.

Believe me, it's tremendously frustating and time-consuming to have to
re-create the mindset that you had some six months or a year ago when
you return to modify some old code from yesteryear.

There are grades of gray. A high-level language with named parameters,
or even more advanced syntaxes can come a long way towards
self-documenting. And it helps to avoid the worst of all: misleading
comments.

Bob Barr wrote:
> > Commenting does not help much if the developer is to
> > maintain an application.
>
> I have to disagree on this point. It is only true (and
> then only to a limited extent) for a program that's
> undergoing active development.
> Over time, many of the things that are readily apparent
> to you now will become vague recollections of your orginal
> thinking.
>
> Believe me, it's tremendously frustating and time-consuming
> to have to re-create the mindset that you had some six
> months or a year ago when you return to modify some old
> code from yesteryear.

My post was a bit vague, sorry.
I do have separate doc with my "mindset that I had some six
months or a year ago"

Olin Lathrop wrote:
> >> However, I could see someone writing 20,000 lines of code
> >> in a high-level language like C++ or Java without comments.
> >> If you have good variable and class names, you could probably
> >> get by and have a small chance of being able to maintain
> >> it. (so-called "self-documenting" code.
> >> It's not a good idea, by any means, but it would be possibble.
> >
> > I did it in VB6. (proper architecture of a solution,
> > well-structured code, meaningful variable, class and subs names)
>
> But WHY?!!
>
> There is no such thing as self-documenting code. Useful symbol
> names provide quick hints to what the symbols are about, but
> they don't substitute for a real explanation. Not by a long
> shot. And, they don't help much in documenting the bigger
> picture. They are just one piece of a much larger solution.

You are right: "bigger picture" has to be documented. And I had
(and still have) rather advanced separate doc behind my code.
But as I see the original post, the discussion was about commenting
inside the code file itself.
I do not advocate uncommented code at all. I just decided to
open all the code to customers to lessen the debates: WHY does
THIS floppy (CDR now) is priced so high - anybody can buy it at
every corner for 25 cents. Without having comments they can't
hack the code or at least they can't be sure they could.

> There are grades of gray. A high-level language with named parameters,
> or even more advanced syntaxes can come a long way towards
> self-documenting. And it helps to avoid the worst of all: misleading
> comments.

> Wouter van Ooijen

Theoretically, COBOL was intended to be self documenting. The choice of
reserved words and the variable naming convention were intended to make
comments unnecessary (not to imply that it worked).

> Theoretically, COBOL was intended to be self documenting. The
> choice of
> reserved words and the variable naming convention were
> intended to make
> comments unnecessary (not to imply that it worked).

It did work, but only at the level it was intended to work for:
individual statements and expressions. But understanding a single
statement is only a small problem: understanding what a whole section
does is more difficult, and understanding why it does that is even
harder. A program can only approach being self-documenting when the
language has abstractions for the higher levels, and allows these levels
to be named appropriately.

>Without having comments they can't hack the code or
>at least they can't be sure they could.

Ah, so you would be an advocate of the code obfuscator that I believe Gimpel
Software (the people that do PC-Lint) have (or had in the past). I believe
it obfuscates C code removing comments and what-have-you for distribution as
source code. Seems that this is the only way to reliably distribute some
packages because of the myriad of *nix systems out there.

>> Theoretically, COBOL was intended to be self documenting. The
>> choice of
>> reserved words and the variable naming convention were
>> intended to make
>> comments unnecessary (not to imply that it worked).

> It did work, but only at the level it was intended to work for:
> individual statements and expressions. But understanding a single
> statement is only a small problem: understanding what a whole section
> does is more difficult, and understanding why it does that is even
> harder. A program can only approach being self-documenting when the
> language has abstractions for the higher levels, and allows these levels
> to be named appropriately.

> Wouter van Ooijen

This problem has been addressed by the method called "structured
documentation" or "literate programming" introduced by Prof. Donald
Knuth of Stanford. His original method, called WEB, was meant for
Pascal and was followed by CWEB for C. Additional versions followed
for other languages, with a generic version called Funnelweb which is
available free on the Internet.
The idea is to combine the executable code and the documentation in
the same source file. Processing this file with one program extracts the
executable source, ready to be compiled or assembled. Using a
different program formats the documentation for printing in TeX so
that a "pretty printed" output file can be produced.
The novel idea here is that the executable code is not presented in one
monolithic listing but rather as short blocks, each of which has
paragraphs of explanatory material accompanying it. The code extraction
program treats these blocks as text macros (in the word processor sense)
and puts them together to make the input to the compiler. The documenation
preparation program adds formatting information to the entire file so that
the blocks are numbered and cross referenced, the code sections are printed
with keywords in bold face, variables names in italic, comments uniformly
indicated, etc. Once you have read a CWEB formatted documentation file, you
may find it difficult to go back to looking at the old style listings.
For a discussion of literate programming , see the discussion at

You can also download Funnelweb there. The various software for implementing
literate programming is specific to the language being documented, so a generic
program like Funnelweb which can handle all languages is especially useful, especially
since it is the only system I know of which can handle PIC assembly code. Funnelweb
even produces HTML output (as well as TeX) for the documentation, so you don't need
a TeX system to print the output.

This is amazing. I asked question about my C code
first replay was no comments.
since then every body started to talk about comments
And later became cobol then Ada then the tag changed to
[EE] soon the tag will be [OT] then will start talk
about some thing else.

Perhaps we have lost the plot here. I take it your original question went
unanswered?. What was your original question - perhaps we can focus on it
more preceisely. Sorry if we tend to wander around a bit..

This is amazing. I asked question about my C code
first replay was no comments.
since then every body started to talk about comments
And later became cobol then Ada then the tag changed to
[EE] soon the tag will be [OT] then will start talk
about some thing else.

andre abelian wrote:
> This is amazing. I asked question about my C code
> first replay was no comments.

I don't remember the original post, but that's probably because discussing
undocumented code is pointless. Why should anyone spend time helping you
when you haven't taken a simple step within your grasp to help yourself?

I appears it would be more efficient in execution than what you are
currently doing.
(If you can place the CASE_Xs in the order of most likely to occur
frequently to least likely to occur frequently -- although I'm not sure if
that will be possible in your application.)

I kind of got lost in the fibers of this thread -- is your problem solved or
are you still having trouble?

>Olin,
>
>That is fine do not help me but let me ask you this
>If(count==28)
>{
>
>}
>what is the different between code below and above
>if(count==28) // if count register = 28
>{
>
>}
>
>to me the code itself says pretty much every thing
>if count = 28 specially I only have one count register.
>I have 10 if statements why should I type same thing
>Next to it.
>

There is no point in putting in comments in that fasion. It would be
much more useful to indicate what a count of 28 means.

if (count == 28) // end of line 1
{

}

or perhaps

if (count == END_LINE1)
{

}

where the constant END_LINE1 is #define'd to 28 elsewhere.

In other words, don't tell (presumably) competent C programmers what
the C code does, they can get that from the code itself. Tell them
(and yourself) why it's doing it.

Bob Barr wrote:
> >if(count==28) // if count register = 28
>
> There is no point in putting in comments in that fasion. It
> would be much more useful to indicate what a count of 28 means.
>
> if (count == 28) // end of line 1

In addition from
"Re: [PIC:] Lookup table modifies PCLATH: How to restore it?":

Olin Lathrop wrote:
+++++++++++++++++++++++++++++++
For example:

incf cnt ;add 1 to CNT

is a useless comment. Comments are way to important to waste
duplicating the assembler manual. You should assume anyone reading your
code is familiar with the language, and therefore already knows that
this instruction will add 1 to CNT. The end of line comment gives you
an opportunity to explain the next level higher intent of the
instruction. For example:

incf cnt ;count one more button press

is a good comment. It tells you something you couldn't otherwise learn
from just this instruction. If you follow this concept, you will find
useful things to say about most lines of code.
+++++++++++++++++++++++++++++++

> -----Original Message-----
> From: Andre Abelian [SMTP:RemoveMEengelecTakeThisOuTEARTHLINK.NET]
> Sent: Monday, September 29, 2003 8:47 AM
> To: PICLISTEraseME.....MITVMA.MIT.EDU
> Subject: Re: [EE:] need help on c code continue
>
> Ken,
>
> I just tried with "if else" it works now I like to know
> the different between if and if else. In witch case I should
> use if only then?
>
> Thank you very much for your help
>
> Andre
>
>
If you string together a whole series of 'if' statments like your first
attempt, the PIC will test every if statement and execute any of them that
evaluate as true. The "if else" construct behaves like a switch statement,
as soon as one expression is evaluated as true, none of the following
expressions will be evaluated.

Mike

=======================================================================
This e-mail is intended for the person it is addressed to only. The
information contained in it may be confidential and/or protected by
law. If you are not the intended recipient of this message, you must
not make any use of this information, or copy or show it to any
person. Please contact us immediately to tell us that you have
received this e-mail, and return the original to us. Any use,
forwarding, printing or copying of this message is strictly prohibited.
No part of this message can be considered a request for goods or
services.
=======================================================================
Any questions about Bookham's E-Mail service should be directed toEraseMEpostmasterbookham.com.

Very little because of the useless comment (Duh). This is a classic case
of how NOT to comment code.

> to me the code itself says pretty much every thing
> if count = 28 specially I only have one count register.

Right. So take the opportunity to explain the next level up. All you've
shown is that it's possible to write bad comments. That doesn't prove
that all comments are bad or that good comments aren't useful.

When writing comments you can assume the reader is familiar with the
language and can see the immediate action of each statement (unless it's
particularly obtuse or unusual, in which case an explanation can help).
This gives you the opportunity to explain the next level higher purpose of
the statement.

In your case, we can assume COUNT is counting something. What is it
counting? What is special about 28? Is it counting up or down? What
should happen when 28 is reached? Here are some examples:

> andre abelian wrote:
>> If(count==28)
>> {
>>
>> }
>> what is the different between code below and above
>> if(count==28) // if count register = 28
>> {
>>
>> }
>
> Very little because of the useless comment (Duh). This is a classic case
> of how NOT to comment code.
>
>> to me the code itself says pretty much every thing
>> if count = 28 specially I only have one count register.
>
> Right. So take the opportunity to explain the next level up. All you've
> shown is that it's possible to write bad comments. That doesn't prove
> that all comments are bad or that good comments aren't useful.
>
> When writing comments you can assume the reader is familiar with the
> language and can see the immediate action of each statement (unless it's
> particularly obtuse or unusual, in which case an explanation can help).
> This gives you the opportunity to explain the next level higher purpose
> of
> the statement.
>
> In your case, we can assume COUNT is counting something. What is it
> counting? What is special about 28? Is it counting up or down? What
> should happen when 28 is reached? Here are some examples:
>
> if (count==28) //done filling the bin?
>
> if (count==28) //max number of retries, error?
>
> if (count==28) //four weeks elapsed, time to give up?
>
> if (count==28) //inventory getting low, time to order more?
>
>
> *****************************************************************
> Embed Inc, embedded system specialists in Littleton Massachusetts
> (978) 742-9014, http://www.embedinc.com
>
> --
> http://www.piclist.com hint: The list server can filter out subtopics
> (like ads or off topics) for you. See http://www.piclist.com/#topics
>

On Tuesday 30 Sep 2003 12:53 am, you wrote:
> Olin,
>
> That is fine do not help me but let me ask you this
> If(count==28)
> {
>
> }
> what is the different between code below and above
> if(count==28) // if count register = 28
> {
>
> }
>
> to me the code itself says pretty much every thing
> if count = 28 specially I only have one count register.
> I have 10 if statements why should I type same thing
> Next to it.

I agree it tells you nothing more but that is because the comment is
inappropriate. I have no idea what count represents or what is special about
the number 28. Maybe this routine is checking daily things so when it gets
to 28 it goes on to exit if the month is February. In which case a more
appropriate comment would be //handle February special case. What is a count
counting? beans, cars, interrupts - who knows so first think about changing
the variable count to something more meaningful.

The point is we know what the test is from the code but we don't know the
significance of the test or the reason for doing it - that is the job of the
comment.

>
> That is fine do not help me but let me ask you this
> If(count==28)
> {
>
> }
> what is the different between code below and above
> if(count==28) // if count register = 28
> {
>
> }
>
> to me the code itself says pretty much every thing
> if count = 28 specially I only have one count register.
> I have 10 if statements why should I type same thing
> Next to it.

You are absolutely right, that kind of commenting is pointless. However,
THIS kind of commenting isn't:

if (count=28) // if number of clock ticks equals 4.6us

Notice the difference? Your comment simply restated what any c programmer
already knew, my comment stated WHAT that code was doing. Many people make
the mistake in thinking comments should describe HOW code works. NO,
comments should describe FOR WHAT REASON code exists. TTYL

> I just tried with "if else" it works now I like to know
> the different between if and if else. In witch case I should
> use if only then?

Hi Andre,

Glad things are working out for you. I see that Jan-Erik and Michael
Rigby-Jones have already answered this question very well, so there is not
much I can add.

But like I said in my previous post, if you do have the ability to know
ahead of time which constants (CASE_1, CASE_2, CASE_3) are most likely to
occur frequently -- test for those constants in the order of most likely to
occur to least likely to occur. This will give you a speed improvement in
your ISR, since on the first match, the multiway if-else statement will
execute the desired block of code and then bail out of the multiway if-else
statement completely (eliminating dead time evaluating subsequent tests).
This advice is also good practice when ordering case values in a switch
statement.

> what is the different between code below and above
> if(count==28) // if count register = 28

Everyone can see that you are interested in count==28, but WHY ?!! Maybe
that's what the comment should say. What condition is that ? The end of
the world ? The day you pay rent ? A comment should not say what the code
does, it should say what it is trying to do symbolically. E.g.:

At the risk of entering a holy war, which this subject is usually part of,
I'll agree with Peter's general point, but also suggest that end of line
code should largely NOT require any understanding of what the code does for
the comment to make sense.

So

> r=inp(788); // read the fudget widget temperature

OK

> foo((float)r/100.0); // log reading

OK

> if(r>450) { // bad, we're on fire

If you don't know exactly what IF means (and if you don't you're in trouble,
but it could be more obscure) then you have to interprept it first.

eg any of these need you to read the code first to see the ACTUAL action.

Russell McMahon wrote:
>> if(R>450) { // If temperature too hot
> or
>> if(R>450) { // If temperature above critical limit
> or
>> if(R>450) { // If we are on fire.
>
> (Note that the if in the above comments just happens to look like the
> instructions if but that is coincidental).
>
> The point is that the code is more or less able to be read without
> understanding first at what the processor actually does (eg
> grazzonking).
>
> Do I always do this? - of course not.
> Is it time consuming? - yes.
> Does it make your code readable? - I think so.

I agree with you in general. I do almost the same thing but word the
comment as a question whenever a decision is being made. This is a
personal preference, but I think makes a little more sense and leaves an
extra character or two of the precious comment space for non-redundant
words. I would write the above as:

if (r > 450) { //too hot?

if (r > 450) { //temperature above critical limit?

if (r > 450) { //on fire?

The implication is that the "exception" program flow will be taken if the
answer to the question is true. This works with conditional skip
instructions just as well:

#define MAX_TEMP 450 (placed in a header file or program location along
with other constants etc., preferably grouped by function)

then in the actual code,

if (r > MAX_TEMP) // Overtemperture Case
{
...........

Then, if I change hardware or requirement etc. I can easily identify &
change the limit to whatever is now appropriate.
Again, a personal preference I guess

Richard P

At the risk of entering a holy war, which this subject is usually part of,
I'll agree with Peter's general point, but also suggest that end of line
code should largely NOT require any understanding of what the code does for
the comment to make sense.

So

> r=inp(788); // read the fudget widget temperature

OK

> foo((float)r/100.0); // log reading

OK

> if(r>450) { // bad, we're on fire

If you don't know exactly what IF means (and if you don't you're in
trouble,
but it could be more obscure) then you have to interprept it first.

eg any of these need you to read the code first to see the ACTUAL action.

> but also suggest that
> end of line
> code should largely NOT require any understanding of what the
> code does for
> the comment to make sense.

Like all things, that depends on your intended audience. If that
audience includes people who don't immediately recognise an if statement
if they see one you are right. But IMHO such people have no business
reading code anyway. In my opinion (but that opinion is based on the
audience I have in mind for my comments - which is mosty me) comments
should never repeat the code, only add to it.

> > but also suggest that
> > end of line
> > code should largely NOT require any understanding of what the
> > code does for
> > the comment to make sense.
>
> Like all things, that depends on your intended audience. If that
> audience includes people who don't immediately recognise an if statement
> if they see one you are right.

Target audience was anyone who needs to know what the writer thought the
code was meant to do but at present has no sure knowledge. That may be
someone else now or myself a month, year or decade later..

The idea was that you are not jumping in and out of the code proper to read
the meaning. You can of course do so if you wish. Obviously not an essential
but makes meaning vvv clear long after you've forgotten ever having written
it. Maybe some people never have that problem :-) .

> Target audience was anyone who needs to know what the writer
> thought the
> code was meant to do but at present has no sure knowledge.

Including
- people who have never seen C before?
- people who have never seen any programming language before?
- people who have never seen english before?
- people who have never seen any human language before?
- 'people' from Tau Ceti who have no experience with any human culture?

I state again: you can't make a sensible comment on commenting (nor on
most other subjects) without stating your point of reference, in this
case the intended audience. And an audience specification that starst
with 'anyone' is highly suspicious :)

When I comment code for my own use my audience is clear: me, but without
recent exposure to the code at hand. In most cases this means commenting
the language consruct itself or even the local function of a statement
is a waste of time (both for the writer and for the reader). Comments
reflect the 'bigger picuture', block comments dominate.

When I comment a 'tutorial' piece of Jal the audience is very different:
just starting to use PICs, some programming experience but probably not
in Jal, probably confused over evry little detail. End-of-line comments
will probably dominate, block comments don't make much sense as the
overall purpose will likely be simple.

By always including "yes" and "no" (which might be other way round
then in the example) you can write the comment to the skip
instruction with "negative" or "positive" logic. It's clear
from the "Yes" and "No" which is which. And placing the third
comment (the "Yes" line in the example) on a line of it's own
helps readability, IMO.

>
>Rather.
>
>> if(R>450) { // If temperature too hot
>or
>> if(R>450) { // If temperature above critical limit
>or
>> if(R>450) { // If we are on fire.
>
>(Note that the if in the above comments just happens to look like the
>instructions if but that is coincidental).

If you start writing your code as a psuedo code, and then fill in the
instructions later, keeping the psuedo code as comments, then this is the
style of comments you will end up with. I find it a good way to set out my
thoughts on how the program needs to work before actually doing the coding.
This allows me to "block structure" the psuedo code, and rip and hack it,
sorting out pieces that can become subroutines, and others that can become
macros, before getting to the hard coding stage.

>> Like all things, that depends on your intended audience. If that
>> audience includes people who don't immediately recognise an if statement
>> if they see one you are right.
>
>Target audience was anyone who needs to know what the writer thought the
>code was meant to do but at present has no sure knowledge. That may be
>someone else now or myself a month, year or decade later..

Hmm, I could see the possibility of a software audit being done by a
programmer not familiar with any assembler language, or by an assembly
language programmer not familiar with some of the more obscure (but valid) C
constructs. Hence the comment needs to add enough suitable information for
the auditor to be happy that the instruction code does do what it is
supposed to.

> If you start writing your code as a psuedo code, and then fill in the
> instructions later, keeping the psuedo code as comments, then this is the
> style of comments you will end up with.
Hallelujah!

When I have a technically complex construct that is often what I do. I write the module fully in pseudo code then copy the block of pseudo code (PC) and intersperse the assembler code between the lines of PC. It even has end of line comments as well :-) (which allows the pseudo code to be closer to the final assembler)(which is the aim).

This is especially useful for eg interrupt driven state machines. I start with a 2D state diagram with states, trigger conditions and actions. Fine for visualisation but terrible for coding from. I convert this to linear pseudo code. I then write real code for the pseudo code, using the pseudo code as block comments. New end of line comments for assembler code get added (sometimes :-) ) as desired.
Having the block of pseudo code at the top of the routine allows you to go back to it for an overview if the line by line gets a bit intractable to follow. Extremely good for subsequent mods.