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!"
I agree with you any time I copy and paste the
code gets messed up so to make it faster I
remove those comments assuming same line repeated
it wouldn't be hard to understand.
>
> 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.
*****************************************************************
Embed Inc, embedded system specialists in Littleton Massachusetts
(978) 742-9014, http://www.embedinc.com
On Sat, 27 Sep 2003 09:25:11 +0400, Mike Singer wrote:
<snip>
>
>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 is no such thing as self-documenting code.
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 is no such thing as self-documenting code.
> 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.
There may be others who do similar packages too.
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
>> > There is no such thing as self-documenting code.
>
> You aint seen Cobol ! :-)
Cobol is not self-documenting, it is self-obfuscating imho. SQL is more or
less self documenting imho, and I heard that Ada is even more so (but I
never used Ada).
Peter
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
>> 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.
John Power
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
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.
Peter L. Peres wrote:
> Cobol is not self-documenting, it is self-obfuscating imho.
> SQL is more or less self documenting imho, and I heard that
> Ada is even more so (but I never used Ada).
Hehe, Peter, - "SQL is more or less self documenting", have
a look at real-life SQL200 stored procedure in TSQL, comments
were removed:
=====================================================
CREATE Procedure AyahAddNewPolyCompsSP
@OrderItemId int =0
, @PolyNumber int = 0
, @PolyTypeId int = 0
As
DECLARE @PolyId Int
SET @PolyId=dbo.AyahGetPolyIdUDF ( @OrderItemId, @PolyNumber )
SET @PolyTypeId=dbo.AyahGetPolyTypeIdUDF ( @OrderItemId, @PolyNumber )
DECLARE @CompQuantity real, @ParentRecId int
DECLARE @CompID int,@StageCount int
SET @StageCount=1
SET @CompID=0
DECLARE @PId int, @SN int , @PR int , @CI int , @CQ real
DECLARE @CompIdSetTab TABLE (
PolyId int
, StageNumber int
, ParentRecID int
, CompID int
, CompQuantity real )
DECLARE @NewStageSetTab TABLE (
PolyId int
, StageNumber int
, ParentRecID int
, CompID int
, CompQuantity real )
DECLARE @StageSetTab TABLE (
PolyId int
, StageNumber int
, ParentRecID int
, CompID int
, CompQuantity real )
INSERT INTO @StageSetTab VALUES (1,1,0,0,1)
DECLARE cursStageSet CURSOR DYNAMIC
FOR SELECT * FROM @StageSetTab
OPEN cursStageSet
WHILE @StageCount < 5
BEGIN
DELETE @NewStageSetTab
FETCH NEXT FROM cursStageSet INTO @PId, @SN, @PR, @CI, @CQ
-- print " FETCH_STATUS=" + LTRIM(STR(@@FETCH_STATUS))
WHILE (@@FETCH_STATUS =0)
BEGIN
DELETE @CompIdSetTab
INSERT @CompIdSetTab SELECT *
FROM
AyahGetCompIdTableUDF(@PolyId,@PolyTypeId,@StageCount,@CI)
INSERT @NewStageSetTab SELECT * FROM @CompIdSetTab
INSERT AyahPolyComps SELECT * FROM @CompIdSetTab
-- print "SN=" + LTRIM(STR (@SN)) + " CI=" +
LTRIM(STR(@CI)) + " RCount=" + LTRIM(STR(@@ROWCOUNT))
FETCH NEXT FROM cursStageSet INTO @PId, @SN, @PR, @CI, @CQ
END
CLOSE cursStageSet
DELETE @StageSetTab
INSERT @StageSetTab SELECT * FROM @NewStageSetTab
-- print " RCount=" + LTRIM(STR(@@ROWCOUNT))
OPEN cursStageSet
SET @StageCount=@StageCount+1
END
GO
==============================================
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
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?
*****************************************************************
Embed Inc, embedded system specialists in Littleton Massachusetts
(978) 742-9014, http://www.embedinc.com
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
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.
Have you tried a multiway if-else statement? (See below)
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?
if ( count == CASE_1 )
{
// <code>
}
else if ( count == CASE_2 )
{
// <code>
}
else if ( count == CASE_3 )
{
// <code>
}
else
{
// <code>
}
Best regards,
Ken Pergola
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
On Mon, 29 Sep 2003 16:53:45 -0700, andre abelian 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.
>
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.
Regards, Bob
-- http://www.piclist.com hint: PICList Posts must start with ONE topic:
[PIC]:,[SX]:,[AVR]: ->uP ONLY! [EE]:,[OT]: ->Other [BUY]:,[AD]: ->Ads
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 to EraseMEpostmasterbookham.com.
Andre Abelian wrote:
> 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?
Depends on what your code needs.
<if>/<else if> is much like a "switch" or "case",
that is, only one (or none if there is no <else>)
statement can be executed at any time.
When using multiple <if>'s, none, one or multiple
statements could be executed. Each separate <if> is
not depending on the other <if>'s in any way.
The other case where you don't need <if>/<else if>, is
of course when you only have one statement.
So, it's more or less up to what you want your
code to do...
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
> 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
>
-- ---
Ake Hedman (YAP - Yet Another Programmer)
eurosource, Brattbergavägen 17, 820 50 LOS, Sweden
Phone: 46 657 413430 Cellular: 46 730 533146
Company home: http://www.eurosource.se
Personal homepage: http://www.eurosource.se/akhe
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
> 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
> 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.:
r=inp(788); // read the fudget widget temperature
foo((float)r/100.0); // log reading
if(r>450) { // bad, we're on fire
scream(FIRE); // this is self-explaining
}
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.
> rjne die_now { // bad, we're on fire - did we know we were jumping?
> rti { // bad, we're on fire - or leaving an
interupt routine?
> grazzonk { // bad, we're on fire - or grazzonking?
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).
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.
It helps to try it on a processor you are not totally used to (perhaps)
(walks something like a PIC, quacks something like a PIC but is not a PIC)
Obviously SOME understanding of the code is going to be necessary, but
miniming it is useful.
LD TempA, AvgSpeedHi ; Get present speed to
LD TempB, AvgSpeedLo ; divide by 16
LD Temp0, #04 ; Initilaise shift-right
counter
BSR4
; RCF ; ensure 0 is being
shifted in / not needed see AND below
RRC TempA ; Do 4 right shifts on Avg
Speed
RRC TempB ; to divide it by 16
djnz Temp0, BSR4 ; Repeat until 4 shifts done.
/ <- need to follow code here
AND TempA, #0fh ; Ensure top 4 bits are zero
SUB AvgSpeedLo, TempB ; Take this 1/16th result from
SBC AvgSpeedHi, TempA ; number it came from = 15/16th left.
ADD AvgSpeedLo, Maths7 ; Now add new speed value
ADC AvgSpeedHi, Maths6 ; both bytes.
; Now move result back to Maths6. Maths7 so following code never knows its
changed.
LD Maths6, AvgSpeedHi ; Move result back to maths
registers
LD Maths7, AvgSpeedLo ; .
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:
skip_ncarr ;no carry into upper byte?
incf level+1 ;propagate the carry
*****************************************************************
Embed Inc, embedded system specialists in Littleton Massachusetts
(978) 742-9014, http://www.embedinc.com
#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.
> rjne die_now { // bad, we're on fire - did we know we were jumping?
> rti { // bad, we're on fire - or leaving an
interupt routine?
> grazzonk { // bad, we're on fire - or grazzonking?
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).
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.
It helps to try it on a processor you are not totally used to (perhaps)
(walks something like a PIC, quacks something like a PIC but is not a PIC)
Obviously SOME understanding of the code is going to be necessary, but
miniming it is useful.
LD TempA, AvgSpeedHi ; Get present speed to
LD TempB, AvgSpeedLo ; divide by 16
LD Temp0, #04 ; Initilaise shift-right
counter
BSR4
; RCF ; ensure 0 is
being
shifted in / not needed see AND below
RRC TempA ; Do 4 right shifts on Avg
Speed
RRC TempB ; to divide it by 16
djnz Temp0, BSR4 ; Repeat until 4 shifts done.
/ <- need to follow code here
AND TempA, #0fh ; Ensure top 4 bits are zero
SUB AvgSpeedLo, TempB ; Take this 1/16th result from
SBC AvgSpeedHi, TempA ; number it came from = 15/16th
left.
ADD AvgSpeedLo, Maths7 ; Now add new speed value
ADC AvgSpeedHi, Maths6 ; both bytes.
; Now move result back to Maths6. Maths7 so following code never knows its
changed.
LD Maths6, AvgSpeedHi ; Move result back to maths
registers
LD Maths7, AvgSpeedLo ; .
> 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.
Just to add to the other fine examples of writing line vomments...
I try to write the comments to the PIC "skip" instructions
something like this :
btfss em_sw_pin ; Is the emergency switch pressed (=high) ?
goto no_em_sw ; No, just continue
; Yes, take care of the em switch !
<process emergency switch...>
no_em_sw
<continue with other tasks...>
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.
This pseudo code be for most processors - in fact for an AVR ATtiny26 - beautiful device :-)
; WHEN DLY300 reaches zero
; IF RXD300Cnt = 0 ; idle if 0
; IF Input low ; Start bit if low
; RXD300Cnt = 10 ; State counter
; DLY300 = 12 ; 1.5 bit times ; wait 1.5 bits ; end
; ELSE ; Still idle ; DLY300 = 2 ; Idle come back 1/4bit later ; end
; ENDIF
FWIW end is a jmp to end of current state machine code.
mitvma.mit.edu with SET PICList DIGEST in the body
