Searching \ for '[PIC] Structuring Assembly Code' in subject line. ()
Make payments with PayPal - it's fast, free and secure! Help us get a faster server
FAQ page: www.piclist.com/techref/microchip/devices.htm?key=pic
Search entire site for: 'Structuring Assembly Code'.

Exact match. Not showing close matches.
PICList Thread
'[PIC] Structuring Assembly Code'
2010\06\14@135702 by Marcel Birthelmer

picon face
I'm hoping [PIC] is the appropriate tag here - if not, I'm sure some
kind soul will take it upon himself to correct me.

I'm starting a new PIC project that will reimplement some logic and
functions from a previous project, this time pulling more of the
functions into the PIC itself. This last project was the first one
with a non-trivial amount of functionality, and I found myself
struggling to keep my assembler code legible and understandable. Now
part of my design considerations for this new project is whether to
use a HLL (C, JAL) since I have significantly more memory than last
time (4KB now vs. 512B last time), but so far assembly still seems
like a good choice.

So to get to the question - those of you that program significant
amounts of code and complicated bits like TCP/IP stacks etc., what do
you do to keep your code structured in a useful way?

2010\06\14@141221 by Olin Lathrop

face picon face
Marcel Birthelmer wrote:
> So to get to the question - those of you that program significant
> amounts of code and complicated bits like TCP/IP stacks etc., what do
> you do to keep your code structured in a useful way?

My answer is partly described and available for free with many examples from
http://www.embedinc.com/pic.

The same basic rules apply whether it's PIC firmware or some other software:

 1 - Break function block into modules.

 2 - Break individual functions within modules into separate
     routines.

 3 - Carefully document all interfaces.  Don't just tell what a
     subroutine does, but exactly what it expects, what it returns,
     pre-conditions, etc.

 4 - Document the purpose of all variables.

 5 - Document the purpose of small chunks of code with paragraph
     comments immediately above them.  Chunks are typically a few
     lines to 1/2 a page or so.  Too small and it will be hard to
     see the forest for the trees.  Too large, and there isn't
     enough documentation.

 6 - Document the purpose of individual lines.

On PICs, we find MPASM doesn't provide sufficient features to allow clean
code to be written.  That's why we have our preprocessor, PREPIC.  Among
other things, it allows for named global flag bits, named I/O pins so that
the specific port and pin is not hard coded where the pin is used, floating
point assembly time calculations, the ability to hook existing MPASM
opcodes, and lots more.  For details, see the PREPIC documentation file.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\14@142450 by Jan-Erik Soderholm

face picon face
On 2010-06-14 19:57, Marcel Birthelmer wrote:
> I'm hoping [PIC] is the appropriate tag here - if not, I'm sure some
> kind soul will take it upon himself to correct me.
>
> I'm starting a new PIC project that will reimplement some logic and
> functions from a previous project, this time pulling more of the
> functions into the PIC itself. This last project was the first one
> with a non-trivial amount of functionality, and I found myself
> struggling to keep my assembler code legible and understandable. Now
> part of my design considerations for this new project is whether to
> use a HLL (C, JAL) since I have significantly more memory than last
> time (4KB now vs. 512B last time), but so far assembly still seems
> like a good choice.
>
> So to get to the question - those of you that program significant
> amounts of code and complicated bits like TCP/IP stacks etc., what do
> you do to keep your code structured in a useful way?

I do not think the issues around this are *that* different
depending on what tool one uses. I come to think about
things like :

- Meaningfull/clear variable names and lables.

- A good overall structure in the code.

- Probably slitting the application into multiple source files
  to keep each file both more readable and also to make bugs
  more "isolated" and easier to track down.

- Modular code also makes it easer to write test-cases that
  runs lower level code without re-writing to much.

None of this is particular specific for assembler.

And of course make use of whatever tools MPASM/MPLINK provides.
(include files, macros, assembly time calculations, external/
global, REServing GPR's in the module that uses them and so on).

Relocatable code is a given, of course.

4KW (not bytes, right ?) is not that much. I guess some
of it will be occupied by tables and other "data" also.


Jan-Erik.

2010\06\14@143602 by Marcel Birthelmer

flavicon
face
>
> I do not think the issues around this are *that* different
> depending on what tool one uses. I come to think about
> things like :
>
> - Meaningfull/clear variable names and lables.
>
> - A good overall structure in the code.
>
> - Probably slitting the application into multiple source files
>   to keep each file both more readable and also to make bugs
>   more "isolated" and easier to track down.
>
> - Modular code also makes it easer to write test-cases that
>   runs lower level code without re-writing to much.
>
> None of this is particular specific for assembler.
>

Of course you're right, and in C etc. I don't have this issue. What
causes me grief is that assembler is so damn verbose. It takes a few
lines to do every miniscule thing, so it's very easy to lose sight of
what you're actually doing.
Something that would take one or two lines in C (I'm using C as an
example since that's what I'm most familiar with on bigger processors)
ends up taking you 10-15 lines in assembly.

I guess the two approaches are writing novel-sized documentation and
using macros wherever possible... The macro approach, depending on
implementation, is almost the first step to a higher-level language
though.

>
> 4KW (not bytes, right ?) is not that much. I guess some
> of it will be occupied by tables and other "data" also.
>


KB - RAM, not flash memory.

2010\06\14@143835 by Vitaliy

face
flavicon
face
Marcel Birthelmer wrote:
> I'm hoping [PIC] is the appropriate tag here - if not, I'm sure some
> kind soul will take it upon himself to correct me.
>
> I'm starting a new PIC project that will reimplement some logic and
> functions from a previous project, this time pulling more of the
> functions into the PIC itself. This last project was the first one
> with a non-trivial amount of functionality, and I found myself
> struggling to keep my assembler code legible and understandable. Now
> part of my design considerations for this new project is whether to
> use a HLL (C, JAL) since I have significantly more memory than last
> time (4KB now vs. 512B last time), but so far assembly still seems
> like a good choice.
>
> So to get to the question - those of you that program significant
> amounts of code and complicated bits like TCP/IP stacks etc., what do
> you do to keep your code structured in a useful way?

Can you give a little more info on the type of chip you're using?

I described an OOP approach that we started using about 2 years ago ("[EE]
Implementing OOP features in C"). It's not a silver bullet, but it has
tremendously improved the quality and maintainability of our code. Following
the prescriptions to the "t" requires some overhead, so the maximum benefit
is realized on relatively large projects (5000+ of lines of code). However,
some of the rules have zero overhead (e.g., naming conventions) and most
have negligible overhead.

Vitaliy

2010\06\14@145427 by Michael Watterson

face picon face
Marcel Birthelmer wrote:
> ...  Now
> part of my design considerations for this new project is whether to
> use a HLL (C, JAL) since I have significantly more memory than last
> time (4KB now vs. 512B last time), but so far assembly still seems
> like a good choice.
>
> So to get to the question - those of you that program significant
> amounts of code and complicated bits like TCP/IP stacks etc., what do
> you do to keep your code structured in a useful way?
>  
Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
comments as if you are trying to understand someone else's code.

You can still use inline or blocks of Assembler. If you really feel you
must. Unless you are doing very high volume or very constrained on
space, consider 18F family.

Even JAL is more easily translated/ported to arbitrary other language on
some non-microchip cpu than the best written assembler.


2010\06\14@151608 by Marcel Birthelmer

flavicon
face
> Can you give a little more info on the type of chip you're using?


Going from an 18F2321 with an external UART-interfaced webserver
(SitePlayer) to an 18F67J60.

The original "memory" comment was probably a bit vague - my point was
that the 18F2321, with its 512 bytes of RAM (384 bytes of which were
basically static information that the code would process every second
or so, plus some UART string parsing) was exhausted fairly quickly.
But now , with a part with 4KB RAM, where the tasks will include a
TCP/IP stack, webserver, all kinds of wacky communications, etc., I'm
doubting my abilities as an assembly programmer when it comes to
organizing that volume of code.

2010\06\14@153938 by Jan-Erik Soderholm

face picon face


On 2010-06-14 21:16, Marcel Birthelmer wrote:
>> Can you give a little more info on the type of chip you're using?
>
>
> Going from an 18F2321 with an external UART-interfaced webserver
> (SitePlayer) to an 18F67J60.
>
> The original "memory" comment was probably a bit vague

To say the least... :-)

> - my point was
> that the 18F2321, with its 512 bytes of RAM (384 bytes of which were
> basically static information that the code would process every second
> or so, plus some UART string parsing) was exhausted fairly quickly.
> But now , with a part with 4KB RAM, where the tasks will include a
> TCP/IP stack, webserver, all kinds of wacky communications, etc., I'm
> doubting my abilities as an assembly programmer when it comes to
> organizing that volume of code.

Well, that's a way other class of processor then I was
thinking of...

2010\06\14@160423 by Bob Blick

face
flavicon
face

On Mon, 14 Jun 2010 19:55:35 +0100, "Michael Watterson" said:

> Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
> comments as if you are trying to understand someone else's code.

Speaking of JAL, is there a current list of supported devices? Enhanced
14 bit instructions?

Looking at the JALv2 site, I couldn't find it, nor is it in any of the
three PDF files I found there.

Thanks,

Bob

--
http://www.fastmail.fm - Accessible with your email software
                         or over the web

2010\06\14@180328 by Michael Watterson

face picon face
Bob Blick wrote:
> On Mon, 14 Jun 2010 19:55:35 +0100, "Michael Watterson" said:
>
>  
>> Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
>> comments as if you are trying to understand someone else's code.
>>    
>
> Speaking of JAL, is there a current list of supported devices? Enhanced
> 14 bit instructions?
>
> Looking at the JALv2 site, I couldn't find it, nor is it in any of the
> three PDF files I found there.
>
> Thanks,
>
> Bob
>
>  
virtually all 10F, 12F, 16F and 18F

see
code.google.com/p/jallib/source/browse/trunk/?r=1655#trunk/include/device
319 devices

I'm doing an 18F67J50 thing in Jalv2


2010\06\14@184215 by Vitaliy

face
flavicon
face
Michael Watterson wrote:
> Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
> comments as if you are trying to understand someone else's code.

Or you can forego the comments and write self-documenting code. :)

Vitaliy

2010\06\14@184734 by Vitaliy

face
flavicon
face
Marcel Birthelmer wrote:
>> Can you give a little more info on the type of chip you're using?
>
>
> Going from an 18F2321 with an external UART-interfaced webserver
> (SitePlayer) to an 18F67J60.

You can definitely benefit from the "OOP in C" approach.

One thing I dislike about the 18Fs is that you have to define extra types to
differentiate the type of memory you're accessing. Have you considered
moving on to a 16-bit PIC?

Vitaliy

2010\06\14@202655 by Tamas Rudnai

face picon face
On Mon, Jun 14, 2010 at 11:41 PM, Vitaliy <spam_OUTpiclistTakeThisOuTspammaksimov.org> wrote:

> Michael Watterson wrote:
> > Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
> > comments as if you are trying to understand someone else's code.
>
> Or you can forego the comments and write self-documenting code. :)
>

There is no such as self-documented code -- only lazy programmers :-)

Comments are telling you what the code meant to do -- as opposed to code,
which tells what did you (or somebody) do. So if you compare the two, you
would see if you (or others) did it correctly.

Tamas




>
> Vitaliy
> -

2010\06\14@211649 by Vitaliy

face
flavicon
face
Tamas Rudnai wrote:
>> > Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
>> > comments as if you are trying to understand someone else's code.
>>
>> Or you can forego the comments and write self-documenting code. :)
>>
>
> There is no such as self-documented code -- only lazy programmers :-)

Your comment seems to imply that there are other kinds of programmers.


> Comments are telling you what the code meant to do -- as opposed to code,
> which tells what did you (or somebody) do. So if you compare the two, you
> would see if you (or others) did it correctly.

Deja vu -- I'm sure we've done this debate already. :)

In a nutshell, if you apply the "loose coupling/tight cohesion" principle,
and use appropriate names for variables and functions, you can eliminate the
need for most comments.

Whenever I see heavy use of comments, it is usually a good indication of
poorly written code.

[FLAME SHIELD ON]

Vitaliy

2010\06\14@213305 by Oli Glaser

flavicon
face


--------------------------------------------------
From: "Michael Watterson" <.....mikeKILLspamspam@spam@radioway.org>
Sent: Monday, June 14, 2010 7:55 PM
To: "Microcontroller discussion list - Public." <piclistspamKILLspammit.edu>
Subject: Re: [PIC] Structuring Assembly Code

{Quote hidden}

I take the simple approach of using whatever can meet the goals of the
project quickest. If it can be done in C, then I use C (possibly with some
assembly stuff called in for optimisation purposes - I hardly ever use
inline) which is usually the way I go for most stuff. If memory and speed
may be a real issue, then I use assembler. With either approach I try to
document stuff properly and keep things well organised and readable, the
extra time/care taken always pays for itself in the end. As mentioned, I use
18F most of the time as you get more for hardly any increase in cost. In
fact I have also really got into the PIC32 recently for a lot of things that
require a modest amount of memory or speed - a bit different and more
complex architecture, but well worth it for any medium to large projects.
Same argument as the 18F over 16F applies, and if volume is not too high
then it can make life a lot easier too. I'd be interested to hear about JAL
and any benefits it may have over C - can it be used for PIC32 also? (I
assume not as you don't mention it, but just checking)


2010\06\14@221031 by Oli Glaser

flavicon
face


--------------------------------------------------
From: "Vitaliy" <.....piclistKILLspamspam.....maksimov.org>
Sent: Tuesday, June 15, 2010 2:16 AM
To: "Microcontroller discussion list - Public." <EraseMEpiclistspam_OUTspamTakeThisOuTmit.edu>
Subject: Re: [PIC] Structuring Assembly Code

{Quote hidden}

Hmmm, not sure if I agree with that one - rather a "brave" statement :-)
Obviously well named variables and functions make life easier and I can see
where you are coming from, but are no direct substitute for comments in a
lot of situations. When reading someone else's code, it can make
understanding things so much quicker, and can save having to skip from file
to file following stuff or guessing at intentions - even with your own code
it can make a big difference. I certainly cannot see how it follows that
heavy use of comments indicates poorly written code - though I note the
"usually". I think it may be more likely the unnecessary stuff might just
indicate over cautiousness and stating the obvious in an attempt to be as
clear as possible. For example "int AddTwoNumbers(int a, int b)" probably
doesn't need a comment stating the obvious, but I can see why people do it
just to be consistent and complete. Comments can be unnecessary or poorly
written *as well* as the code being so (maybe more likely if code is written
badly) but I tend to think that part of writing code well (of any reasonable
size/complexity) *includes* well written and appropriate commenting.




2010\06\14@221649 by ivp

face picon face
> Whenever I see heavy use of comments, it is usually a good
> indication of poorly written code

To me it indicates that there's someone who, like many,

(a) won't be able to remember in 6 months time what a snippet of code
does and why it was done in that particular  way

(b) is being kind to others who read it

(c) has been though the code and justified/explained it to themselves
(perhaps not necessarily carefully but at least has attempted to) ....

(d) .... and therefore, hopefully, understands or is on the way to
understanding, the code

Poorly-written code and poorly-written comments don't have to go
hand-in-hand. Both are sets of facts and either could be completely
wrong without making other also wrong

For example, below might or might not be 'heavy' use of comments, as
almost every line has one, but it explains to me the functions and paths
of this section. At some time in the future I'm sure this will save me a
lot of time if I need to modify it or understand it again

Even if I added a paragraph of explanation before this code I would
still comment. The comments, labels, and mnemonics as a package
tell me exactly what I want to know

not_ok   bcf     mpow         ;motor power relay off
        nop
        nop
        bcf     mdir         ;motor direction relay off

chk_btns btfsc   but_up       ;check for Down or Up button
        goto    up           ;Up pressed
        btfss   but_dn       ;Down pressed
        goto    chk_btns     ;neither

down     call    _251a        ;read opto number into temp0
        movlw   .20          ;compare with Down limit
        xorwf   temp0,w
        bnz     ok_dn        ;not limit, motor on, Down
        call    tx           ;send as current opto number
        goto    not_ok       ;at limit, don't move down

        goto    done         ;finished

done     display "Joe"          ;indicate end of post

 end

run

Joe

2010\06\15@000716 by RussellMc

face picon face
<Flaming hat shields ...>

> > Whenever I see heavy use of comments, it is usually a good indication of
> > poorly written code.
> > [FLAME SHIELD ON]

> Hmmm, not sure if I agree with that one - rather a "brave" statement :-)

Nah. That's not brave. Just trolling :-).
Consider:

- "Heavy" & "usually"  can be defended subsequently as a matter of
interpretation.

- He's loaded for Ol.. er, Bear. "Some people" advocate commenting in
a style that could be adumbrated to be criticised  heavily by such a
remark, and they might be expected to come running. Might. (I probably
comment code at about the level tat Olin advocates, but, that's
another story.)

- How many people have you EVER had to ask to document their code LESS.

- How many of the many many many papers etc written on good
programming that you have met have recommended reducing documentation?

- How many listings have you read where you wished there were LESS
comments. (And how many where you wished there were more?).

- If you read your OWN code after 1/6/60 months do you tend to wish
for more or less comments.

- Short of a major problem, how many people are going to write comment
material in detail BECAUSE their code is poor. The implication is that
the documentation is perceived to be needed to make the code work
better (hasn't worked from Ada on), or to make people THINK your code
is good (some may look at documentation as primary evidence - most
just run the code first and see what it does.

- Would you buy a good low mileage only driven by a little old
man/woman on Sunday's horse/car/other from someone who advocated less
or lower levels of or minimal commenting?

- How well correlated, in your experience, are  copious commenting and
the attributes and poor attitude that lead to poorly written code.

- It's 4pm Friday - I'm really looking forward to a weekend of
commenting my code".
- Nah, sorry mate, I can't get to the party, I have to ...
- I was running up against the deadline so I had to double the commenting.
- It would be  completely obvious to any fish waving moron what this
port bit does, so I added a paragraph of comments.
...
____________________

There are, arguably, 5 levels of comments or related documentation levels.

Project description. Sets the stage

Per module or block or ...
ALL modules blocks will have SOME comments.
Usually will describe functionality.
Usually will list variables/parameters and may and describe them
unless well established at higher level.

Per paragraph of code - 1 to some lines. Commonly (1<= Some <= 10),
maybe 10-20, seldom > 20 depending on level of language and type of
routine. eg N lines of identical inline shifting, fall through  NOP
stacks for isochronous timing adjustment etc will merit less comment.
All 'paragraphs' will have some form of comment

End of line or equivalent. Many or most lines will have such.

Variable/label/function/subroutine/ ... / names - self documenting.

No?

:-)


                   Russell

2010\06\15@004728 by John Gardner

picon face
Lots of good discussion in "Code Complete", emanating from
the unlikely locus of Redmond.

No doubt the miscreant was removed from the "campus" with
prejudice when the CSA heard of it...

Jack

2010\06\15@013305 by Wouter van Ooijen

face picon face
> You can definitely benefit from the "OOP in C" approach.

Recently I had to do some small modifications on a project that was done
"OOP in asm". All variables resided in objects, and pointers to those
objects were passed around. The silly thing was that there was only one
instance of each object... Maybe worse was that there were almost no
comments (and little other documentation), and half of it was subtly out
of phase with the code.

So maybe there is a place for "OOP in XXX" (where XXX is a non-OOP
language) but it raises the possibilities for horrible code to a next level.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@013427 by Wouter van Ooijen

face picon face
>> Whenever I see heavy use of comments, it is usually a good indication of
>> poorly written code.

In my experience the correlation (if any exists) is the other way round.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@022727 by William \Chops\ Westfield

face picon face
One of the things that makes assembly faster than higher level  
languages is the possibility of using lightweight and informal  
parameter passing between subroutines.

One of the main things you should do if you are writing larger  
assembly language programs is to formalize a more robust and general  
purpose parameter passing mechanism for subroutines...  ditto for  
"local variables"

Macros that implement complex data structures are also very useful, as  
well as those that let you implement some program control without  
having to sprinkle obnoxious labels all over.

Basically, you want as many of the features that high-level-language  
people have found to be useful as you can get without having to  
actually use a language that doesn't fit the actual processor  
architecture.  (arguably, C succeeded because it was pretty close to  
being a snazzy assembler
for a rather large suite of processors...)

As Olin said, MPASM isn't quite up to the task :-(

BillW

2010\06\15@022846 by Tamas Rudnai

face picon face
On Tue, Jun 15, 2010 at 2:16 AM, Vitaliy <piclistspamspam_OUTmaksimov.org> wrote:

> Tamas Rudnai wrote:
> >> > Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
> >> > comments as if you are trying to understand someone else's code.
> >>
> >> Or you can forego the comments and write self-documenting code. :)
> >>
> >
> > There is no such as self-documented code -- only lazy programmers :-)
>
> Your comment seems to imply that there are other kinds of programmers.
>

Recent years I rarely can see other kinds of programmers :-)


> Deja vu -- I'm sure we've done this debate already. :)
>

Do not worry, that was only adjusting the Matrix :-) But yes, we have been
discussing this already.

In a nutshell, if you apply the "loose coupling/tight cohesion" principle,
> and use appropriate names for variables and functions, you can eliminate
> the
> need for most comments.
>
> Whenever I see heavy use of comments, it is usually a good indication of
> poorly written code.
>

Interesting to see your experience. My observation was the opposite:
Whenever a programmer is lazy to comment, also lazy to write good and
self-documenting code.

Tamas



>
> [FLAME SHIELD ON]
>
> Vitaliy
>
> -

2010\06\15@023857 by Tamas Rudnai

face picon face
On Tue, Jun 15, 2010 at 5:06 AM, RussellMc <@spam@apptechnzKILLspamspamgmail.com> wrote:

> - How many people have you EVER had to ask to document their code LESS.
>

I remember only one occasion: That was the time of 8 bit microcomputers. My
Father had this Apple II, and some programmers were developing a budget
calculator for him. Applesoft Basic were storing the comments in memory as
it was an interpreted language, therefore they run out of the 64KB RAM
because of the nice but huge comments they were doing :-)

Tamas



{Quote hidden}

> -

2010\06\15@025701 by Wouter van Ooijen

face picon face
>> - How many people have you EVER had to ask to document their code LESS.

Assembly program beginners (and sometimes C beginners too) tend to
comment what the instructions do, like

movlw 0x20 ; load value 0x20 into W

n++; /* make n equal to n + 1 */

I tell them to leave such comments out.

OK, I also ask them to comment *why* 0x20 must be loaded in W, or why n
must be incremented.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@032933 by Vitaliy

face
flavicon
face
RussellMc wrote:
> Nah. That's not brave. Just trolling :-).

No Russell, I'm not trolling. Honest.


> - He's loaded for Ol.. er, Bear. "Some people" advocate commenting in
> a style that could be adumbrated to be criticised  heavily by such a
> remark, and they might be expected to come running. Might. (I probably
> comment code at about the level tat Olin advocates, but, that's
> another story.)

Consider the possibility that we are both right. Olin's tool of choice is
assembler. The scope of my comment was limited to C.


> - How many people have you EVER had to ask to document their code LESS.

Someone actually told me more than once that I documented my code too much,
and that comments impeded his understanding of the code. This was before the
truth was revealed to me.


> - How many of the many many many papers etc written on good
> programming that you have met have recommended reducing documentation?

How many books teach waterfall as a valid project development methodology?
Why do both feel so unnatural?

The trend is changing. Our desktop brethren already embraced agile
methodologies, which advocate exactly what sounds so ridiculous to you: LESS
documentation.


> - How many listings have you read where you wished there were LESS
> comments. (And how many where you wished there were more?).

I don't recall wishing for either, anytime recently. I do recall thinking
many times, "this code can use some serious refactoring".


> - If you read your OWN code after 1/6/60 months do you tend to wish
> for more or less comments.

It hasn't been 60 months since we adopted the methodology. But I can easily
find my way around in code I wrote 1.5 years ago, and in my partner's code.


> - Short of a major problem, how many people are going to write comment
> material in detail BECAUSE their code is poor. The implication is that
> the documentation is perceived to be needed to make the code work
> better (hasn't worked from Ada on), or to make people THINK your code
> is good (some may look at documentation as primary evidence - most
> just run the code first and see what it does.

You don't have to go far. Look at Microchip's 18F library. It's a
wonderfully documented mess of a code.


> - Would you buy a good low mileage only driven by a little old
> man/woman on Sunday's horse/car/other from someone who advocated less
> or lower levels of or minimal commenting?

Sorry, I don't understand your metaphors.


{Quote hidden}

Texbook style, followed it faithfully for years. Description for the module,
function block describing function purpose and parameters.

Nowadays have maybe one comment per 100 lines of code, only where necessary.
Why? The magic of "loose coupling, tight cohesion". The module name
describes its purpose. The header file contains all the access functions (a
small number, because public functions are the enemy of loose coupling).
Each function does exactly what its name says. Same goes for parameters.


> Variable/label/function/subroutine/ ... / names - self documenting.
>
> No?

Yes, but I suspect we would disagree on the definition of "self
documenting". Most people's code isn't self documenting enough, hence the
need for copious amounts of commenting.

Vitaliy

2010\06\15@033901 by Vitaliy

face
flavicon
face
Wouter van Ooijen wrote:
>>> - How many people have you EVER had to ask to document their code LESS.
>
> n++; /* make n equal to n + 1 */
>
> I tell them to leave such comments out.
>
> OK, I also ask them to comment *why* 0x20 must be loaded in W, or why n
> must be incremented.

I tell new programmers, "ALWAYS use meaningful variable names and NEVER use
magic numbers".

   numberOfNewStudents = UiHandler_GetNumberOfNewStudents();
   studentCount = studentCount + numberOfNewStudents;

Vitaliy

2010\06\15@035850 by Wouter van Ooijen

face picon face
> I tell new programmers, "ALWAYS use meaningful variable names and NEVER use
> magic numbers".

That does help, but it is not the end. Some magic numbers are more clear
when used magically than when #defined somewhere. This 2 should *not* be
#defined somewhere else:

n = n << 2; // multiply by 4 to get the word offset

In assembly, registers don't have meaningful names :( But this is a few
parts of a graphics LCD driver:

   #define R_IOSET     R5
   #define R_IOCLR     R6
   #define R_SET_ALL   R7
   #define R_XCLR      R8
   #define R_MASK      R9
   #define R_TEMP      R10

   LDR R_IOCLR,   =MKT_IO0CLR
   LDR R_IOSET,   =MKT_IO0SET
   LDR R_SET_ALL, =SET_ALL
   LDR R_XCLR,    =SET_XSCL
   LDR R_MASK,    =SET_DATA

      // set XSCL and D0..D3
      STR R_SET_ALL, [ R_IOSET ]

      // shift 4 data bits to the correct position
      // and mask all other bits off
      AND R_TEMP, R_MASK, \REG, lsl #GLCD_D0

      // write D0..D3
      STR R_TEMP, [ R_IOCLR ]


--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@040008 by Vitaliy

face
flavicon
face
Wouter van Ooijen wrote:
>>> Whenever I see heavy use of comments, it is usually a good indication of
>>> poorly written code.
>
> In my experience the correlation (if any exists) is the other way round.

It will be "he said, she said" until we look at some actual code examples.

It also depends on your definition of "poorly written code". Based on your
response to "n++" in your students' code ("use a comment to explain why
you're incrementing n"), I think it's safe to say that our definitions are
quite different.

The statement I made is controversial because it contradicts a long-standing
programming dogma. However, if you think about it, it makes perfect sense:
poorly written code requires a lot of explaining. Well written code requires
little or none.

Four years ago, I bought a Chinese MP3 player, that requires you to make a
series of non-intuitive button presses to perform simple tasks. To turn up
the volume up two clicks, you have to press [MODE][MODE][NEXT][NEXT][MODE].
You must read the manual to figure out how to fast forward or switch between
the player function and the picture viewer.

The iPhone has a volume control on the side, so the same operation is
completely effortless. Even complicated tasks are easy, because the
interface is so well thought out. The iPhone doesn't come with a manual.

Vitaliy

2010\06\15@040924 by Marcel Birthelmer

flavicon
face
On Tue, Jun 15, 2010 at 12:46 AM, Vitaliy <KILLspampiclistKILLspamspammaksimov.org> wrote:
> Marcel Birthelmer wrote:
>>> Can you give a little more info on the type of chip you're using?
>>
>>
>> Going from an 18F2321 with an external UART-interfaced webserver
>> (SitePlayer) to an 18F67J60.
>
> You can definitely benefit from the "OOP in C" approach.
>
> One thing I dislike about the 18Fs is that you have to define extra types to
> differentiate the type of memory you're accessing. Have you considered
> moving on to a 16-bit PIC?

I did consider a PIC32 with ethernet MAC (as well as other ARM etc.
type processors), but even though this is mostly a one-off right now,
I can't help but feel that the price point is overwhelmingly in favor
of the PIC18 (especially since it includes the PHY).

2010\06\15@042052 by Vitaliy

face
flavicon
face
ivp wrote:
>> Whenever I see heavy use of comments, it is usually a good
>> indication of poorly written code
>
> To me it indicates that there's someone who, like many,
>
> (a) won't be able to remember in 6 months time what a snippet of code
> does and why it was done in that particular  way
>
> (b) is being kind to others who read it
>
> (c) has been though the code and justified/explained it to themselves
> (perhaps not necessarily carefully but at least has attempted to) ....
>
> (d) .... and therefore, hopefully, understands or is on the way to
> understanding, the code

I wish I could show you some of our code, so you would understand that
comments aren't necessary to achieve all of the nice things you listed
above. Alas, it's proprietary, but I am willing to answer legitimate
questions from those who decide to consider the subject with a sincere heart
and an open mind. :)


> Poorly-written code and poorly-written comments don't have to go
> hand-in-hand. Both are sets of facts and either could be completely
> wrong without making other also wrong

My premise is, perfect code doesn't need comments. Of course, no one writes
perfect code, but if you approach code writing with this mindset and strive
to write self-documenting code, you will find your need for comments greatly
reduced and in many cases, eliminated.


> For example, below might or might not be 'heavy' use of comments, as
> almost every line has one, but it explains to me the functions and paths
> of this section. At some time in the future I'm sure this will save me a
> lot of time if I need to modify it or understand it again

My comments are meant to be taken in the context of the C language. I have
close to zero experience with assembler. I'm sure some of the concepts are
transferrable, you can simulate procedures and "objects", but as we all know
TANSTAAFL: OOP comes at a price (bigger overhead) and if you start using it
in assembler you would probably be better off writing your program in a
higher level language in the first place.

Vitaliy

2010\06\15@042758 by Vitaliy

face
flavicon
face
Tamas Rudnai
> Interesting to see your experience. My observation was the opposite:
> Whenever a programmer is lazy to comment, also lazy to write good and
> self-documenting code.

I've been through the phases. Like everyone else, I wrote spaghetti code and
named my variables "asdf;lkj". Then under the influence of my professors and
some of the books/articles I read, I started commenting my code religiously.
It never felt "right", though.

Writing self-documenting code is not easy, but practice makes perfect, and
with time it becomes second nature. And refactoring never feels like a waste
of time, like commenting often does.

Vitaliy

2010\06\15@044056 by Vitaliy

face
flavicon
face
Wouter van Ooijen wrote:
>> You can definitely benefit from the "OOP in C" approach.
>
> Recently I had to do some small modifications on a project that was done
> "OOP in asm". All variables resided in objects, and pointers to those
> objects were passed around. The silly thing was that there was only one
> instance of each object... Maybe worse was that there were almost no
> comments (and little other documentation), and half of it was subtly out
> of phase with the code.
>
> So maybe there is a place for "OOP in XXX" (where XXX is a non-OOP
> language) but it raises the possibilities for horrible code to a next
> level.

You may remember when I first started looking into OOP for C, Xiaofan
suggested a couple of articles where the authors were emulating C++ in C.
IMO their implementations are a huge overkill, and I would have probably
failed miserably if I followed in their footsteps, because I'm not 1/10 as
good a programmer as they are.

Luckily, an author of a book on patterns suggested, "favor aggregation over
inheritance". If you don't use inheritance in your code, the task of
emulating OOP in a procedural language is greatly simplified, and you still
get 90% of the benefits.

Vitaliy

2010\06\15@050438 by Wouter van Ooijen

face picon face
> The statement I made is controversial because it contradicts a long-standing
> programming dogma. However, if you think about it, it makes perfect sense:
> poorly written code requires a lot of explaining. Well written code requires
> little or none.

But as others mentioned, code with comments is more likely to be written
by someone who has put at least some effort into the work, which has
some correlation with writing good code.

Note that the correlation breaks down the moment you start measuring it
and acting on the measurements. This is something that is often
overlooked by the quality guys.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@053550 by RussellMc

face picon face
BCCs - should blow away a few cobwebs:


> Four years ago, I bought a Chinese MP3 player, that requires you to make a
> series of non-intuitive button presses to perform simple tasks. To turn up
> the volume up two clicks, you have to press [MODE][MODE][NEXT][NEXT][MODE].
> You must read the manual to figure out how to fast forward or switch between
> the player function and the picture viewer.


Aha!

[RCL] ,   [CHS] + [7] + [8]

That shows my age.
GoFlo will explain it :-).

I never owned one, alas.
I had 21 65 25 ... ?
I'd like a 35 - the one that properly started it all [tm].

                 Russell

2010\06\15@071212 by ivp

face picon face
> My premise is, perfect code doesn't need comments. Of course, no
> one writes perfect code, but if you approach code writing with this
> mindset and strive to write self-documenting code, you will find your
> need for comments greatly reduced and in many cases, eliminated

Ah, perhaps I misunderstood your meaning of "poorly written". Are
you talking about *how* the code is written - the label and variable
names for example - rather than the efficiency of (possibly poorly-
constructed) code ?


2010\06\15@080008 by Olin Lathrop

face picon face
Oli Glaser wrote:
> For example "int AddTwoNumbers(int a, int b)" probably
> doesn't need a comment stating the obvious,

Of course not, that's why you state the unobvious.  In this case natural
questions would be why is this function here at all?  Why is the built in
"+" operator insufficient?

> Comments can be unnecessary or poorly
> written *as well* as the code being so

Yes, writing good comments takes skill, just like writing good code.  The
two go together.  One can not replace the other since they serve different
purposes.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@082440 by Olin Lathrop

face picon face
'William Chops" Westfield ' <RemoveMEwestfwTakeThisOuTspammac.com wrote:
> One of the main things you should do if you are writing larger
> assembly language programs is to formalize a more robust and general
> purpose parameter passing mechanism for subroutines...

I have done that.  First I define a set of "general registers" REG0...REGn
in unbanked memory.  Usually, parameters are passed to subroutines in these
registers, and return values also in these registers.  Also, the general
assumption is that subroutines preserve all the general registers they don't
specifically return values in.

Of course specific routines can break these guidelines when there is a good
reason to do so, but then must go out of their way to warn about the unusual
interface.  I usually write a comment in the subroutine header like:

;   WARNING:  Trashes REG0, REG1, REG4.

> ditto for "local variables"

That makes no sense.  Being local, they are invisible to callers outside the
module so there can't be any rules about them in that context.  Inside a
single module you are a bit more free to do something unusual since its
scope is contained.  You still of course need to document it carefully.
Still, I can't think of what formal rules should apply to local variables.

> As Olin said, MPASM isn't quite up to the task :-(

Have you tried PREPIC?  It adds a lot of cool features to PIC assembler.
Doc file at http://www.embedinc.com/pic/prepic.txt.htm


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@082903 by Olin Lathrop

face picon face
Wouter van Ooijen wrote:
>> - How many people have you EVER had to ask to document their code
>> LESS.
>
> Assembly program beginners (and sometimes C beginners too) tend to
> comment what the instructions do, like
>
> movlw 0x20 ; load value 0x20 into W
>
> n++; /* make n equal to n + 1 */
>
> I tell them to leave such comments out.
>
> OK, I also ask them to comment *why* 0x20 must be loaded in W, or why
> n must be incremented.

So this isn't a request to comment less, but comment better, and is part of
the important process of teaching your students to comment well.
Unfortunately, teaching good commenting is something all too rare.
Personally, I think source code submitted to a programming class should be
graded about equally on functional content and documentation.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@084248 by Olin Lathrop

face picon face
Vitaliy wrote:
>     numberOfNewStudents = UiHandler_GetNumberOfNewStudents();
>     studentCount = studentCount + numberOfNewStudents;

The thing you seem to be missing is that there is a tradeoff between what
you can explain with symbol names and what you can explain with comment.  If
you make your symbol names too verbose, it takes away end of line comment
space that could possibly be used to explain some wrinkle no amount of
variable naming could explain.  It also makes it more difficult to visually
see the structure of the code.  For example, it takes a little longer to
visually parse your second line above to see that it has the basic structure

 A <-- A + B

Conversely, some information can be succinctly explained with symbol names.
Comments and symbol names are different, and when used effectively
complement each other to provide good documentation in a way either alone
couldn't.

You have essentially chosen to phanatically push one to the extreme at the
expense of the other.  Not good.

In your example above, we can see that new students are being added to the
count of students, but are these students of a particular class, the whole
school, something else?  Or is this maybe in a general purpose subroutine
that deals with a pile of students and it's up to the caller to understand
the scope of this pile.  All of these are legitimate, but those kinds of
questions are better answered by good comments in various places.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@084617 by Olin Lathrop

face picon face
Vitaliy wrote:
> poorly written code requires a lot of
> explaining. Well written code requires little or none.

This is where you're wrong.  Well written code may require a little less
explaining, but no amount of verbose and carefully chosen symbol names can
provide the kind of information that good comments can.  The two work
together.  It's not a question of which one is best.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@084713 by Wouter van Ooijen

face picon face
> So this isn't a request to comment less, but comment better

More or less. occasionally there are comments that can be left out
without replacing by something else.

Note that it is not entirely the students faults: a comment is there to
state the non-obvious. But to a first-week asm progger it is really
non-obvious that MOVLW loads a constant value into W... So commenting
skill must grow with programming skill.

> Unfortunately, teaching good commenting is something all too rare.

Unfortunately only a few of my fellow teachers have done any serious
programming in their career. They are 100% teachers.

> Personally, I think source code submitted to a programming class should be
> graded about equally on functional content and documentation.

I wish I was allowed to do that. As it is, I must conform to a certain
percentage of students completing a course successfully. (Yes, really!
if, let's say, only 50% succeeds *I* have a problem!). There is enough
challenge in getting them to write anything that resembles working code.
I do reward good comments, but punishing the absence would be too much.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@084858 by Olin Lathrop

face picon face
Vitaliy wrote:
> I wish I could show you some of our code, so you would understand that
> comments aren't necessary to achieve all of the nice things you listed
> above. Alas, it's proprietary,

Surely you can disclose a module or two of maybe a few 100 lines total that
is not implementing a central function of your business?


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@085412 by Oli Glaser

flavicon
face


--------------------------------------------------
From: "Olin Lathrop" <spamBeGoneolin_piclistspamBeGonespamembedinc.com>
Sent: Tuesday, June 15, 2010 1:00 PM
To: "Microcontroller discussion list - Public." <TakeThisOuTpiclistEraseMEspamspam_OUTmit.edu>
Subject: Re: [PIC] Structuring Assembly Code

> Oli Glaser wrote:
>> For example "int AddTwoNumbers(int a, int b)" probably
>> doesn't need a comment stating the obvious,
>
> Of course not, that's why you state the unobvious.  In this case natural
> questions would be why is this function here at all?  Why is the built in
> "+" operator insufficient?

In this case, the function is "here" merely as an illustration of a point -
I would be asking serious questions of myself if this ever actually got used
in any of my code :-)

>> Comments can be unnecessary or poorly
>> written *as well* as the code being so
>
> Yes, writing good comments takes skill, just like writing good code.  The
> two go together.  One can not replace the other since they serve different
> purposes.

Yep, that is the general essence of what I was trying to point out.


> ********************************************************************
> Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
> (978) 742-9014.  Gold level PIC consultants since 2000.
> --

2010\06\15@093512 by John Ferrell

face
flavicon
face
Most, may be all of us have been here before. This round I believe the
question is simply too vague. The correct answer is context sensitive.
The code I write contains information to guide ME after I have
forgotten. It would be different if I were teaching something to some
one else. It would also be different if I were turning the code to some
one else to modify/maintain, (think client/customer). There is not a
single answer that fits all. SOME structure is desirable in all cases.
Unstructured and Uncommented Spaghetti code is never justifiable.

The rules Olin has offered are a good general case...

Just my opinion , of course.

John Ferrell, W8CCW

On 6/14/2010 1:57 PM, Marcel Birthelmer wrote:
{Quote hidden}

2010\06\15@094508 by Marcel Birthelmer

flavicon
face
On Tue, Jun 15, 2010 at 3:35 PM, John Ferrell <RemoveMEjferrell13spamTakeThisOuTtriad.rr.com> wrote:
> Most, may be all of us have been here before. This round I believe the
> question is simply too vague. The correct answer is context sensitive.
> The code I write contains information to guide ME after I have
> forgotten. It would be different if I were teaching something to some
> one else. It would also be different if I were turning the code to some
> one else to modify/maintain, (think client/customer). There is not a
> single answer that fits all. SOME structure is desirable in all cases.
> Unstructured and Uncommented Spaghetti code is never justifiable.
>
> The rules Olin has offered are a good general case...
>
> Just my opinion , of course.


John,
I'm not sure how the question is too vague - my problem, as stated, is
that on projects i've worked on with assembly code, I end up with
something that's hard to read and follow, and I'm not sure how to go
about structuring it any better. Hence my request for other people's
methods.
I'm not sure that there is much difference between hobby code and
commercial code, either... if I'm working on something intermittently
over a few months' time, there are bound to be parts of the code that
will be revisited only after several weeks/months, and those will sure
look foreign to me at first glance. And I definitely don't want to
have to reacquaint myself with the ugly mess of code each time.
I did get some valuable insights, and I'm going to see how I can adapt
those to my situation.
- Marcel

2010\06\15@113728 by Alan B Pearce

face picon face
> I'm not sure how the question is too vague - my problem, as stated, is
> that on projects i've worked on with assembly code, I end up with
> something that's hard to read and follow, and I'm not sure how to go
> about structuring it any better. Hence my request for other people's
> methods.

Being a person who is inherently unstructured in any sort of work, I
like to write out the proposed code in "high level pseudo code" without
any actual code that will assemble/compile. Then when I have
changed/restructured/whatever other changes deemed appropriate I then
use this pseudo code as the comments, and write the actual code in
between lines of the comment pseudo code. This may end up having a block
of the pseudo code as a large multi-line comment, or single lines of
pseudo code as a comment to a block of code.

Otherwise I tend to start coding, and find that I haven't taken into
account something, and end up having to rewrite considerable amounts of
code, instead of a few lines of pseudo code.

The pseudo code can start of as very broad brush stroke code, which can
get refined in several passes as I determine what variables are
required, and what blocks can be changed to make suitable subroutines
which can be used in multiple places by having suitable call parameters.
--
Scanned by iCritical.

2010\06\15@120858 by PICdude

flavicon
face
With non-PIC code (Java, C, etc), I don't have this problem, but my  
assembly code has gotten "messy" when I plunge right into it ,and I  
too have re-written things to better organize it.  I've found that  
simple flowcharting helps tremendously here.

Cheers,
-Neil.



Quoting alan.b.pearceEraseMEspam.....stfc.ac.uk:

{Quote hidden}

> -

2010\06\15@123422 by sergio masci

flavicon
face


On Mon, 14 Jun 2010, Vitaliy wrote:

> Michael Watterson wrote:
> > Use JAL (or  C) for 10F/12F/16F/18F and write reusable libraries with
> > comments as if you are trying to understand someone else's code.
>
> Or you can forego the comments and write self-documenting code. :)
>

I cringe when I hear people talking about "self-documenting code". Not
because I'm an advocate of "heavily commented code" but because I feel
"self-documenting code" AND "heavily commented code" both miss the
point!

Code should be written so as to be easy to follow and maintain. Adding the
odd comment here and there is necessary when the code is doing something
obscure. But the comment itself does nothing to improve the code. It
doesn't tell the compiler / assembler / macro processor etc what the code
is trying to do, what exceptions to look out for, what side effect are
taking place, or aything else. Comments can be misleading to the human
trying to understand what the code is trying to do. In my experience,
reducing the volume of comments actually causes the programmer /
maintainer to read the source much more carefully and work out what the
code is actually doing rather than just skimming it and relying on the
comments to understand what is going on.

I've had to dig through a great many peoples code during the course of my
carear and the number of times I've found a mismatch between the code and
the comments is incredibly high. People fix code but are less prone to
fixing comments. Sometimes someone will fix a piece of code in one place
and not realise that the fix has implications on comments in some other
place. The compiler / assembler etc doesn't warn you. It can't it doesn't
understand the corrolation between the comments and the code. Sometimes
people just rip a piece of code from one place and embed it somewhere else
(comments and all) without understanding the comments at all. Then they
hack it to fit in with the new code and before you know it the old
comments are just a misleading waste of time.

Heavy commenting == BAD

Light commenting == not so BAD but why is it necessary? Why is the code
obscure such it needs commenting?

Regards
Sergio Masci

2010\06\15@132640 by Olin Lathrop

face picon face
sergio masci wrote:
> Light commenting == not so BAD but why is it necessary? Why is the
> code obscure such it needs commenting?

If you haven't learned that yet, no amount of PIClist posts will teach it to
you.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\15@134712 by Isaac Marino Bavaresco

flavicon
face
Em 15/6/2010 09:46, Olin Lathrop escreveu:
> Vitaliy wrote:
>  
>> poorly written code requires a lot of
>> explaining. Well written code requires little or none.
>>    
> This is where you're wrong.  Well written code may require a little less
> explaining, but no amount of verbose and carefully chosen symbol names can
> provide the kind of information that good comments can.  The two work
> together.  It's not a question of which one is best.
>  

There are certain cases that I can't imagine how to make fully
self-commenting code:

1) Routines that implement communication protocols, are much easier to
understand with comments that correlate the code statements with what
they do in the protocol, or even embed parts of the protocol
specification into the code.
2) Certain code optimizations make the code very hard to understand and
need a lot of comments to explain how the code works.

Isaac

__________________________________________________
Fale com seus amigos  de graça com o novo Yahoo! Messenger
http://br.messenger.yahoo.com/

2010\06\15@151201 by Vitaliy

face
flavicon
face
ivp wrote:
>> My premise is, perfect code doesn't need comments. Of course, no
>> one writes perfect code, but if you approach code writing with this
>> mindset and strive to write self-documenting code, you will find your
>> need for comments greatly reduced and in many cases, eliminated
>
> Ah, perhaps I misunderstood your meaning of "poorly written". Are
> you talking about *how* the code is written - the label and variable
> names for example - rather than the efficiency of (possibly poorly-
> constructed) code ?

Correct. I say "poorly written" for lack of a better term.

Vitaliy

2010\06\15@170142 by Wouter van Ooijen

face picon face
> Light commenting == not so BAD but why is it necessary? Why is the code
> obscure such it needs commenting?

Code can be very clear about what it is doing - good code might need
little or no comments for that.

But for a reader it is often more interesting to know *why* the code is
doing what it is so clearly doing.

Somewhere in the code of my shop's administration I will either multiply
an amount by FACTOR_VAT, or leave it as-is. It is clear what is being
done: in some cases I need to charge VAT, in others I don't. The
EC/Dutch rules for this are a bit complicated, so a comment could point
to a document clarifying these rules. One might argue that such a
pointer belongs in the specifications, not in a comment. Maybe. In an
ideal world. Sometimes.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\15@183256 by Tamas Rudnai

face picon face
On Tue, Jun 15, 2010 at 10:01 PM, Wouter van Ooijen <EraseMEwouterspamvoti.nl> wrote:

> But for a reader it is often more interesting to know *why* the code is
> doing what it is so clearly doing.
>

Could not say better than that!

Tamas



{Quote hidden}

> -

2010\06\15@185657 by William \Chops\ Westfield

face picon face

>> ... or you can forego the comments and write self-documenting  
>> code. :)

Enough.  There are at least four different types of comments:

1) You can comment how the code itself works, especially when tricky  
things are happening:
      swapf  STATUS,w    ;put unchanged STATUS in w with nibbles  
reversed.
 or
       } /* time for new brightness */
     } /* while forever */


2) You can document the algorithm that the (piece of) code is  
implementing:
    /*
     * We have a random number in each PWMx between 1 and 128
     * and we're going to have 128 cycles of delay.  So each
     * decremented value can only cross zero once, at which
     * time we toggle the output state.
     */
 or
    ;; standard code from http://piclist.com/math for 32bit multiply  
by 10.


3) You can document what the code does at a higher level:
    /*
     * This implements the IP checksum as defined in RFC791, a long  
with
     * special functions to update and recompute when we do a TTL  
decrement.
     * See RFC1122 (requirements for internet hosts and RFCxxxx  
(properties of
     * the ip checksum algorithm) for additional details.  This code  
does NOT
     * handle IP options that change value at each hop.
     */

 or

     ;; OBD protocol low-level bit banging.  Matches NSTI-1998  
version of spec
     ;;  tested against GYA-17 homologation suite.


4) You can document the history of the code:
    ;PS:<6-1-MONITOR>TCPTCP.MAC.43, 25-Mar-86 00:42:41, Edit by BILLW
    ; advertize optimistic windows based on number of interupt level
    ; buffer that are available at NUWNDO.
 or
    /* Be careful when checksum hits magic values; see bugID 1234 */
 and
    /* This is version 1.0 of the shipping XYZ code ! */

    (oh yeah; no one has mentioned this yet: use some form of version  
control
     software, and document/checkin changes are a relative fine  
granularity!)


All of these are "important" to some degree, especially for "large  
projects",
and no one style of documentation is likely to adequately cover them  
all...
"self documenting code" is clearly unsuitable for at least three of  
them.

Now, many "projects" never achieve a complexity of code, algorithm,  
conformance,
and history that is likely to require major attention to ALL of these  
for the same
line of code.  But you should think about them all at least a little  
bit!

BillW

2010\06\15@192235 by Tamas Rudnai

face picon face
Sorry about me again, I really should shut my mouth up, just one more thing
came into my mind:

My favourite negative examples of commenting are nearly all GNU projects.
Usually there is a huge comment section at the top of the source, but that
only tells boring stuff like GNU licence and the like. They rarely actually
tell what the actual source is about, which module is that, sometimes not
even the name of the project it belongs to. I do not like spending hours
figuring out which module does what just because someone did not want to
spare 5 minutes to write 2 sentences -- if you know what I mean.

Tamas


On Tue, Jun 15, 2010 at 11:56 PM, William "Chops" Westfield
<RemoveMEwestfwEraseMEspamEraseMEmac.com>wrote:

{Quote hidden}

> -

2010\06\15@200829 by Chris Roper

picon face
I tend to use the OP's suggestion of macro's to simulate a high level
language and split the project into several Include files and have a
lot of defines.
The inline comments then act as a sort of flow description, the macro
comments the function and the header the overall object of the code.
But I am a hardware person by training, software is my second
language, so I like to build programs the way I do hardware, by wiring
predefined and tested bits together.

2010\06\15@202404 by Brendan Gillatt

flavicon
face
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 15/06/2010 16:37, RemoveMEalan.b.pearcespam_OUTspamKILLspamstfc.ac.uk wrote:
{Quote hidden}

I second that notion. I find that thinking the system through using
flowcharts, psuedo-code and perhaps the odd bit of Python helps
enormously. Without producing a proper structure, even in rough, for what
I plan to implement costs me several times as much in time than it would
had I planned it properly.

- --
Brendan Gillatt | GPG Key: 0xBF6A0D94
brendan {a} brendangillatt (dot) co (dot) uk
http://www.brendangillatt.co.uk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (MingW32)

iEYEARECAAYFAkwYGaAACgkQHEhZ5Ws5poHVgwCbB4PcK4Ef4aETviH8O2S5uqxy
I+cAoIqAr6JlXuMxTuCHVqnI7TGFuSnW
=2Ua+
-----END PGP SIGNATURE-----

2010\06\15@205525 by John Gardner

picon face
> ...and perhaps the odd bit of Python ...

Care to elaborate? I have no Python experience.

thanks, Jack

2010\06\15@220643 by ivp

face picon face
> I have no Python experience

"There is only one thing in the world worse than having no
Python experience ....."

(Give us a bit of the wit, Oz)

2010\06\15@222058 by John Gardner

picon face
> Give us a bit of the wit, Oz...

By all means :)

Jack

p.s. - I'm still curious about the conjunction of pseudo-code
        and Python...

2010\06\15@224421 by Vitaliy

face
flavicon
face
Wouter van Ooijen wrote:
>> Light commenting == not so BAD but why is it necessary? Why is the code
>> obscure such it needs commenting?
>
> Code can be very clear about what it is doing - good code might need
> little or no comments for that.
>
> But for a reader it is often more interesting to know *why* the code is
> doing what it is so clearly doing.
>
> Somewhere in the code of my shop's administration I will either multiply
> an amount by FACTOR_VAT, or leave it as-is. It is clear what is being
> done: in some cases I need to charge VAT, in others I don't. The
> EC/Dutch rules for this are a bit complicated, so a comment could point
> to a document clarifying these rules. One might argue that such a
> pointer belongs in the specifications, not in a comment. Maybe. In an
> ideal world. Sometimes.

I would not object to this kind of comment.

Vitaliy

2010\06\16@082320 by sergio masci

flavicon
face


On Tue, 15 Jun 2010, Olin Lathrop wrote:

> sergio masci wrote:
> > Light commenting == not so BAD but why is it necessary? Why is the
> > code obscure such it needs commenting?
>
> If you haven't learned that yet, no amount of PIClist posts will teach it to
> you.
>

Eh? Teach me what?

Regards
Sergio Masci

2010\06\16@085433 by Isaac Marino Bavaresco

flavicon
face
Em 15/6/2010 21:24, Brendan Gillatt escreveu:
> > Being a person who is inherently unstructured in any sort of work, I
> > like to write out the proposed code in "high level pseudo code" without
> > any actual code that will assemble/compile. Then when I have
> > changed/restructured/whatever other changes deemed appropriate I then
> > use this pseudo code as the comments, and write the actual code in
> > between lines of the comment pseudo code. This may end up having a block
> > of the pseudo code as a large multi-line comment, or single lines of
> > pseudo code as a comment to a block of code.
>
> I second that notion. I find that thinking the system through using
> flowcharts, psuedo-code and perhaps the odd bit of Python helps
> enormously. Without producing a proper structure, even in rough, for what
> I plan to implement costs me several times as much in time than it would
> had I planned it properly.
>


I like to comment assembly code embedding the corresponding C code as
end-of-line comments, aligned vertically sometimes after the 80th column.

Sometimes I start with C code, compile to assembly and then start
optimizing it. The original C code inserted as comments by the compiler
become my comments, and the comments I put into the C code end there
also, then I have a fairly well commented assembly code.

Of course sometimes it is impossible to express some assembly sequences
as (organized) C code, then I use pseudo-code the more like C as possible.


As a rule, I like to have my assembly modules available in C also, as a
reference and a starting point for porting to other platforms.


Isaac

__________________________________________________
Fale com seus amigos  de graça com o novo Yahoo! Messenger
http://br.messenger.yahoo.com/

2010\06\16@091435 by Byron Jeff

flavicon
face
On Wed, Jun 16, 2010 at 12:26:23PM -0400, sergio masci wrote:
>
>
> On Tue, 15 Jun 2010, Olin Lathrop wrote:
>
> > sergio masci wrote:
> > > Light commenting == not so BAD but why is it necessary? Why is the
> > > code obscure such it needs commenting?
> >
> > If you haven't learned that yet, no amount of PIClist posts will teach it to
> > you.
> >
>
> Eh? Teach me what?

That good comments are necessary whether or not the code is obscure. Here's
a simple example from a outdoor light controller I wrote nearly 10 years
ago:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Note that for these two routines that W contains the month offset.
; In this way it can get the sunrise/sunset value for the current month or
; the next month, which is required to compute the difference over the span
; of the month. Note that January is repeated at the end of the list so that
; The december values can be computed without modification to the routines.

sunrise addwf   month,W
       addlw   255             ; Subtract 1 to offset for month from 1-12
       addwf   PCL,F
       dt      163,154,126,85,49,28,31,50,72,92,117,144,163

sunset  addwf   month,W
       addlw   255             ; Subtract 1 to offset for month from 1-12
       addwf   PCL,F
       dt      40,69,94,118,141,163,172,158,123,82,45,29,40
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Taking another look at the comment, I forgot to note that the values are
the number of minutes offset from 5AM for sunrise and 5PM for sunset
respectively. Also that this system does not try to account for Daylight
Savings time and runs all year in Standard Time.

Even the small comment in the routine describes why the addlw 255 is
there.

That's the point. 10 years later I can look at the comments for this
routine and have a pretty good idea of how it works. A bit more complicated
example from the program is the usage of these tables to set the specific
sunrise/sunset value for a particular day. I didn't want to have a table
with 365/366 values for each day. So I used linear interpolation between
the offsets of two consecutive months above to approximate the
sunrise/sunset time. Here's that code:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Set the sunrise/sunset time. We do this by interpolating the sunrise/sunset
; times at the beginning of the month. Linear interpolation over a 32 day
; month is done because it makes the fixed binary arithmatic easier. The basic
; algorithm
; 1) Get the current month's first day time
; 2) Get the difference from next month's time. Divide by 32.
; 3) Add 1/32 for each day into the month. Truncate to an integer minute.
; 4) Add/subtract the extra minutes from the 1st day offset
; 5) Adjust the offset to the correct minute/hour time for that day.

; We only need to do this once a day at midnight.

setset  movlw   1
       call    sunset          ; Get the sunset offset for the next month
       movwf   sunnext
       movlw   0               ; Get the sunset offset for this month
       call    sunset
       movwf   sunoff
       movlw   17              ; Start of the offset time 5:00 PM
       movwf   sunhour
       call    interp
       movf    sunhour,W
       movwf   sshour
       movf    sunmin,W
       movwf   ssmin
       return


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Finally the interpolation routine is complicated. So like the others,
there's an explanation at the top. This time virtually every line of code
has a comment describing its purpose:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
interp                          ; Interpolate the sunrise/sunset time
                               ; input in sunoff/sunnext/sunhour
                               ; Result in sunhour/sunmin
       movf    sunoff,W        ; Get the offset for the current month
       subwf   sunnext,W       ; Find the difference between the two
offsets
       movwf   sunsign         ; Keep the sign
       btfsc   sunsign,7       ; Check the sign bit
       sublw   0               ; Negate by subtracting W from 0.
       movwf   sunnext         ; Negate if negative. Sign still in sunsign

; We treat sunnext as a III.FFFFF fixed number. We need to multiply this
; offset by the number of days since the beginning of the month. However
; If the sum exceeds 1 we need to take the integer part and add/subtract it
; from the original offset and then remove it from our running sum

       clrf    sunfract        ; Start at zero
       movf    day,W           ; Get the current day
       addlw   255             ; Subtract one. This is our count
       btfsc   STATUS,Z        ; Done if first day of the month.
       goto    sscont2
       movwf   c1              ; Put in counter
ssloop  movf    sunnext,W       ; Get the fraction
       addwf   sunfract,W      ; Add to the current fraction
       movwf   sunfract
       movwf   tempw           ; Save so we can shift and swap
       rrf     tempw,F         ; Shift
       swapf   tempw,W         ; Swap. III now in low three bits of W.
       andlw   7               ; Ditch the rest.
       btfsc   sunsign,7       ; See if we need to subtract
       sublw   0               ; Negate W if we need to subtract.
       addwf   sunoff,F        ; Add to the offset
       movlw   0x1f            ; Only keep the fractional part
       andwf   sunfract,F      ; So mask off the integer part in sunfract
       decfsz  c1,F            ; Loop
       goto    ssloop

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

It's not self commenting. And the comments are not unnecessary. In fact
looking at it 10 years later, it's a pretty good use of a fixed point
algorithm. But I wouldn't even want to try to figure out how it worked
without the comments.

And that's the point Olin is trying to make.

BAJ
--
Byron A. Jeff
Program Coordinator: IT/CS/CNET
College of Information and Mathematical Sciences
Clayton State University
http://cims.clayton.edu/bjeff

2010\06\16@092255 by Brendan Gillatt

flavicon
face
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 16/06/2010 01:55, John Gardner wrote:
>> ...and perhaps the odd bit of Python ...
>
> Care to elaborate? I have no Python experience.
>
> thanks, Jack

Python is really very nice to jot down outlines of algorithms with: it's
structure for loops is very clean and there are no parenthesis to deal
with. In fact it's syntax is similar to common pseudo-code, with the
added benefit that I can run the code without much trouble if needs be.
(See the example code in
http://en.wikipedia.org/wiki/Bresenham's_line_algorithm for example).

Say I wanted to set all the pins of a port with 1 second intervals
between them I could plan this with a section of Python:

for pin in range ( 8 ):
       set_pin ( pin )
       wait ( )

The alternative in a flowchart would be something like:

( START )
  |
( pin = 0 )
  |
  |-------------+
  |             |
( Set pin )      |
  |             |
( pin ++ )       |
  |             |
< pin > 7? >--N--+
  |
  Y
  |
( DONE )

which is obviously a bit more cumbersome.

I believe Pascal is the traditional language to quickly describe working
code with, though I have no experience with it.
- --
Brendan Gillatt | GPG Key: 0xBF6A0D94
brendan {a} brendangillatt (dot) co (dot) uk
http://www.brendangillatt.co.uk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (MingW32)

iEYEARECAAYFAkwY0CgACgkQHEhZ5Ws5poFIsACfcmKEO4tFLyfUzvxoq9AxMIE7
SrUAnRJ2IWGJGwtdTwpShG/qaEUduDbS
=YmJ2
-----END PGP SIGNATURE-----

2010\06\16@092456 by SME

picon face
--0016e68fa338b179c1048925a56e
Content-Type: text/plain; charset=ISO-8859-1

>> I wish I could show you some of our code, so you would understand that
>> comments aren't necessary to achieve all of the nice things you listed
>> above. Alas, it's proprietary,

> Surely you can disclose a module or two of maybe a few 100 lines total that
> is not implementing a central function of your business?

Attached is an example of extreme commenting.
If people wish, it can be used as an example of how these comments
could be replaced by code without comments.
The reason that such an extreme amount of commenting is unnecessary
could also be explained.

The text below has been truncated at 60 characters per line to show
what the code to comment ratios are, but to avoid email system line
folding . The same  code but untrimmed is provided in the attached
file.

This is for an interesting processor - it has only AND but not OR -
(or the other way around) it is now so long since this was writtten
that I do not remember which it is. I have not met another processor
where Demorgan's theorum was an essential part of programming, rather
than an option.


____________________


valid3key

;validrkey

; <KKH2>        Here add a little bit of daring (with some d
;       Now that a valid key has been pressed The record lin
;          be set low (active).
;       This has the affect of precharging the microphone ca
;       and is aimed at reducing the initial "click" when re
;       If recording is NOT wanted the line must be de-asser
;       CS being taken low to avoid recording.


; **********    With MICON separate from RECORD this should
;               The microphone can be enabled without riskin

;       The above has been diminished in danger by reading B
;       only lowering record if a record is requested. This
;       not be early enough to prevent clicks and taking thi
;       to before the last serial in will re-introduce the d
;       NOTE that the code should not be taken back into the
;       loop or the microphone would be on during normal key
;       thereby drawing current when unneeded.
;       IF the time added by this routine excessively increa
;       delay (unlikely) the call to sout16 could be arrange
;       when a change in the write request line status has o
;       The write request line is not explicitly debounced b
;       with other delays and should be effectively debounce

;       Note that the Brecording flag is NOT changed (code w
;       do this is commented out) as this is an "operational

               jrr     Bsinrecreq, sindata, preset_brec ; jr if record re
;                                                          i
               set     sout2pr, sout2nd        ; set record line high
               set     sout2micon, sout2nd ; Microphone off
               jp      preres_brec

; ##########################################################

preset_brec     res     sout2pr, sout2nd        ; set record
               res     sout2micon, sout2nd ; Microphone on

; Bugfix!?: 30.10.97 - don't allow extend to be decremented
;       This was happening on sequential recordings when the
;       held on between records.

               ld      a, K6lextend    ; get extend count
               cpi     a, 0            ; if at zero leave i
               jrz     nodec

               dec     K6lextend       ; Take 1 from extend
                                       ; always contain at
                                       ; and extend is only
nodec

               jp      putrecstatus    ; K6L 20.8.97

preres_brec                             ; K6L 20.8.97

; K6L 20.8.97
;       If we are here any level-extends achieved by record-
;       should be cancelled as we are not recording.

               ldi     K6lextend, 0    ; Not recording so a

putrecstatus    ; K6L 20.8.97
               call    sout16
               ldi     wdr, watchtim   ; keep watchdog at bay

; <KKI4>
Last_Chance

;       It appears we are all ready to go.
;       Now we optionally ofer a "user debounce period based
;       settings sin2data bits 0 to 2. If these are non zero
;       about 80 milliseconds per count (0 to 7 counts) ther
;       key activation delays of up to 7 x 80ms = 560 millis
;       The LED is lit at the start of this period so that u
;       see that their keypress is actually achieving someth

               ld      a, sin2data     ; get DipSwitch settings
               andi    a, 07h          ; keep only 3 lsb's
               jrnz    user_delay      ; jr if user delay is wanted
               jp      no_delay        ; jp if no delay

; ##########################################################

user_delay

; <KKI5 greatly remodelled to use irq timerud >

;       Delay for user selected period

               ld      ud_temp, a      ; save delay value
               sla     a               ; double it
               add     a, ud_temp      ; add to initial value --> 3 x mul
               ld      ud_temp, a      ; save tripled value
               
               set     sout2led, sout2nd ; show that something is happeni
               call    sout16
               
               ld      a, ud_temp      ; get tripled value
               ld      timerud, a      ; set irq timer to N x 3 x 37.5ms
               ld      timerud, a      ; = N x 0.1125 seconds

;       We will now loop while the same key is held down unt
;       the user releases the key or the "tremor" delay time
;       There are 2 paths through this loop to account for b
;       and remote keyboards.

ud_loop
               jrs     local, keymode, ud2_loop   ; b if main keyboard

       ; Here if remote keyboard

               call    SIN4       ;) Remote Kbd testing
               call    SINKEY     ;) Remote Kbd testing
               jp      ud3_loop   ;) Remote Kbd testing

       ; ***********

       ; Main keyboard

z908
ud2_loop        call    KEYIN           ; Get present key va
       
       ; Both keyboards

ud3_loop    cp      a, rawkeycode   ; and see if user has pe
               jrnz    back_off       ; jr if not same key, user has give
               
               ld      a, timerud      ; check timer for expiry
               jrz     GoManGo         ; jr / go for SRB ignition on time
               jp      ud_loop         ; jp / still same key pressed so f
               
; ##########################################################


               ; same key not pressed, main engine shutdown
back_off
               res     sout2led, sout2nd ; show that something stopped ha
               call    sout16

               jp      no_key

; ##########################################################

GoManGo         ; (note that LED is on)

no_delay        ; liftoff

; <KKI4 end>
; <KKI5 start>
;       Briefly flash LED to show record start.
               
               res     sout2led, sout2nd       ; LED off
               call    sout16
               ldi     a, 014h                 ; for 50 ms
               call    sdelay
               set     sout2led, sout2nd       ; and on again
               call    sout16
; <KKI5 end>


; **********************************************************
;
;       A stable valid keypress has been detected.
;       This is the stage at which we are committed to actio
;       having been pressed. This code will be processed to
;       an ISD address based on keymapping dipswitch setting
;       will be taken based on whether we are in record, pla
;       mode.

               ld      a, rawkeycode   ; get validated keycode
               andi a, 1FH             ; use only 5 lower bits
       
       ; Change code to match binary key numbers
       
               ldi drwr, keymangle.w   ; point to lookup table
               ldi x, keymangle.d      ;.
               add a, x
               ld x, a
               ld a, (x)
               ld      Vkeycode, a     ; save modified keyc

       ; A now contains a 5 bit key number
       ; Translate keycode into speech address
       ; Original A is destroyed
       ; Results are in talkadhi & talkadlo (raw codes) & t

               call    keymap          ; Translate code in A to address

; <KKJ3G> - use talkdurn to control sleep timing
;
;       As a key has been pressed reset sleep timer to stop
;       sleep.
;
;       As the talk duration value is a direct multiple of t
;       timer_pd interupt delay of 3.75s when its value is 0
;       may be used to set timer_pd when key delays are long
;       done timer-pd may time out and put the system to sle
;       talking is finished.

               ld      a, talkdurn
       ; FALLTHROUGH 970813                 cpi     a, 0ch
       ; K6:  ALWAYS JUMP  jrc     var_pd  ; jr if big key
       ; K6L: Always jump also

       ; FALL THROUGH 970813              jp      var_pd  ;

var_pd
       ; Use variable power down delay

; K6L: This is rubbish for a K6L - will need to work on fina


               inc     a       ; Make the delay a little larger to avoid
               inc     a       ; clipping the end of speech.

; MODIFICATION NEEDED
; K6L temporary

               jrs     Bk6l, keymode, k6ltimerpd   ; j if a
               jp      k6timerpd
k6ltimerpd

;       get keylev delay flag

               ld      a, talkdurn
               andi    a, 00000001b    ; 16.8.97

;       convert to either 32 key mode = 1 or all others = 2

               addi    a, 01   ; becomes 1 for 32 key mode
               ld      v, a    ; push delay

;       add 1 extra leylev delay per extend count

               cpi     a, 1            ; If cnt is one we a
               jrz     addonce         ; j if in 32 key mod
                                       ; per extend_count

               add     a, K6lextend    ; else add an extra
addonce
               add     a, K6lextend    ; add again (or once

               ld      K6lrectime, a   ; save K6L recording
               inc     a               ; extend time for sh
               inc     a
k6timerpd

;       Bugfix (actually bug bypass) 28.8.97 1030 ish
;       The speaking time for extended keys is less than the
;       This can be confirmed by recording on level 1 with o
;       a message fills most of level 1 and level 4. When th
;       back, some is missing. However, if level 4 is played
;       message is heard. Conclude: That timer_pd is shuttin
;       IF this is what is wrong, rather than finding out wh
;       by doubling the time provided.
;       NOTE: Investigation shows that the time spoken for v
;       always less than the correct time). This MAY be due
;       decrementing of timer_pd relative to other timers as
;       an interupt driven prescaler.
;       GOTCHA (I think). Clearing timer2z prescaler seems t



               SLA     A               ; double max allowab
               ld      timer_pd, a     ; save delay to shut
                 ld      timer_pd, a
               clr     timer2z         ; Clear prescaler -

       
;                       .=.=.=.=.=.=.=.=

atlast

;       At last, my address is whole again !
;       ISD slot address is in talkadhi/talkadlo
;       Now we need to decide what to do with it.
;
; Choices are -
;
;       CONTROL
;       Added at K6L
;
;               Key may never get as far as speaking
;
;       RECORD
;               Recording continues while the same key remai
;               the time allotted to the key is not exceeded
;               keyup is required before the next key can be
;
;                       Calculate & output address, lower IS
;                       Lower ISD/CS
;                       Start key duration timer
;                       ? LED on ?
;                       While key down  -
;                               leave ISD/CS down
;                               if timer expires
;                                       Raise ISD/CS
;                                       idle loop until keyu
;                       Keyup           - Raise ISD/CS
;                                       - pulse ISD/PD hi/lo
;
;       PLAY - No Repeat
;
;               A single low pulse of CS is provided. A key
;               will idle loop until released. To initiate a
;               the next key must be pressed after the curre
;               finishes.
;
;                       Calculate & output address
;                       Pulse ISD/PD hi/lo (resets any prior
;                       Pulse ISD/CS lo/hi
;                       While key down   - idle loop
;
;       Play - Repeat   Calculate & output address
;
;               Monitoring of EOM/OVF is needed. When a key
;               held down when a sequence terminates a new C
;               initiated. Permanent output of CS would not
;               the following message(s) would be sequential
;
;                       Lower ISD/CS
;                       ? LED on ?
;                       Pulse  ISD/CS lo/hidown
;                       While key down  -
;                               if EOM low going edge
;                                       Wait till EOM goes h
;                                       Pulse ISD/CS lo/hi
;                       Keyup           Pulse ISD/PD hi/lo
;

; ==============================
;
;       First some initialisation of flags which will be use
;       proper action.

; 1.
;       Find out if the user is attempting to record.
;       set "Brecording" if user wishes to record.
;       Note flags is 1 on record but request line is low on

               jrr     Bsinrecreq, sindata, set_brec ; jr if record reque
;                                                       is l
               res     Brecording, flags ; reqres high - not recording
               jp      res_brec

; ##########################################################

; zzzz1
set_brec        set     Brecording, flags ; reqres low  - in
res_brec
;
onthefly
;               "ON THE FLY" key processing
;
; 2.X - Added at K6L - see if this is an "on the fly" contro
;
; The "otf" controls are:
;       9.8.97:  Changing of levels     in 32 key mode.
;       3.9.97:  Single key rotating level change.
;       3.9.97:                         and in 16 key mode
; These will be fairly hard coded here.
; Later on more generality will be required.

; 32 key mode level setting from keyboard

       jrr     Bk6l, keymode, nototf32         ; j/bypass i
       jrs     Brecording, flags, nototf32     ; j/bypass i
       jrs     B32key, keymode, testotf1       ; j to otf i
       jrs     B16key, keymode, testotf1       ; j to otf i

       jp      nototf32

testotf1

;       If here, we are in 32 or 16w keymode and not recordi
;       See if the key pressed is a level shift key.
;       LS keys are currently in the LH column of 4 keys.
;       Codes (after keymap) are 00h, 04h, 08h, 0Ch.
;       To test the level keys against the current level the
;       to be translated into the levels 0,1,2,3.
;       While "clever" coding could be used the easiest meth
;       explicit test and set for each value.
;

; "As it happens" the key codes output by Keymangle are iden
; those used here so the translation is un-needed SO FAR but
; leave it in so we can make change easily.

               ld      a, Vkeycode             ; get saniti
               andi    a, 00011111b            ; ensure onl

; If a "real" translation was happening the keycodes to be t
; appear in the following line eg  cpi a,"keycode"
; The keycodes from keymangle start at "00" in the bottom lh
; increment by row and then by column.

               cpi     a, 00h                  ; Key = 00?
               jrnz    not0a                   ; j if not k
               ldi     a, 00h                  ; else trans
               jp      lshift01                ; and go to
not0a
               cpi     a, 01h                  ; Same as ab
               jrnz    not0b
               ldi     a, 01
               jp      lshift01
not0b
               cpi     a, 02h                  ; Same as ab
               jrnz    not0c
               ldi     a, 02h
               jp      lshift01
not0c
               cpi     a, 03h                  ; Same as ab
               jrnz    not0d
               ldi     a, 03h
               jp      lshift02
not0d
               jp      nototf32

;       ****************

--0016e68fa338b179c1048925a56e
Content-Type: text/plain; charset=US-ASCII; name="Comments.txt"
Content-Disposition: attachment; filename="Comments.txt"
Content-Transfer-Encoding: base64
X-Attachment-Id: f_gai6yo150

dmFsaWQza2V5DQoNCjt2YWxpZHJrZXkNCg0KOyA8S0tIMj4gICAgICAgIEhlcmUgYWRkIGEgbGl0
dGxlIGJpdCBvZiBkYXJpbmcgKHdpdGggc29tZSBkYW5nZXIpDQo7ICAgICAgIE5vdyB0aGF0IGEg
dmFsaWQga2V5IGhhcyBiZWVuIHByZXNzZWQgVGhlIHJlY29yZCBsaW5lIHdpbGwgbm93IA0KOwkg
IGJlIHNldCBsb3cgKGFjdGl2ZSkuDQo7ICAgICAgIFRoaXMgaGFzIHRoZSBhZmZlY3Qgb2YgcHJl
Y2hhcmdpbmcgdGhlIG1pY3JvcGhvbmUgY2FwYWNpdG9ycw0KOyAgICAgICBhbmQgaXMgYWltZWQg
YXQgcmVkdWNpbmcgdGhlIGluaXRpYWwgImNsaWNrIiB3aGVuIHJlY29yZGluZy4NCjsgICAgICAg
SWYgcmVjb3JkaW5nIGlzIE5PVCB3YW50ZWQgdGhlIGxpbmUgbXVzdCBiZSBkZS1hc3NlcnRlZCBw
cmlvciB0bw0KOyAgICAgICBDUyBiZWluZyB0YWtlbiBsb3cgdG8gYXZvaWQgcmVjb3JkaW5nLiAN
Cg0KDQo7ICoqKioqKioqKiogICAgV2l0aCBNSUNPTiBzZXBhcmF0ZSBmcm9tIFJFQ09SRCB0aGlz
IHNob3VsZCBub3QgYmUgbmVjZXNzYXJ5Lg0KOyAgICAgICAgICAgICAgIFRoZSBtaWNyb3Bob25l
IGNhbiBiZSBlbmFibGVkIHdpdGhvdXQgcmlza2luZyByZWNvcmRpbmcuDQoNCjsgICAgICAgVGhl
IGFib3ZlIGhhcyBiZWVuIGRpbWluaXNoZWQgaW4gZGFuZ2VyIGJ5IHJlYWRpbmcgQnNpbnJlY3Jl
cSBhbmQgDQo7ICAgICAgIG9ubHkgbG93ZXJpbmcgcmVjb3JkIGlmIGEgcmVjb3JkIGlzIHJlcXVl
c3RlZC4gVGhpcyBsb2NhdGlvbiBtYXkgDQo7ICAgICAgIG5vdCBiZSBlYXJseSBlbm91Z2ggdG8g
cHJldmVudCBjbGlja3MgYW5kIHRha2luZyB0aGlzIGNvZGUgYmFjayANCjsgICAgICAgdG8gYmVm
b3JlIHRoZSBsYXN0IHNlcmlhbCBpbiB3aWxsIHJlLWludHJvZHVjZSB0aGUgZGFuZ2VyLg0KOyAg
ICAgICBOT1RFIHRoYXQgdGhlIGNvZGUgc2hvdWxkIG5vdCBiZSB0YWtlbiBiYWNrIGludG8gdGhl
IG1haW4gaWRsZSANCjsgICAgICAgbG9vcCBvciB0aGUgbWljcm9waG9uZSB3b3VsZCBiZSBvbiBk
dXJpbmcgbm9ybWFsIGtleWxlc3MgaWRsZSBtb2RlDQo7ICAgICAgIHRoZXJlYnkgZHJhd2luZyBj
dXJyZW50IHdoZW4gdW5uZWVkZWQuIA0KOyAgICAgICBJRiB0aGUgdGltZSBhZGRlZCBieSB0aGlz
IHJvdXRpbmUgZXhjZXNzaXZlbHkgaW5jcmVhc2VzIGtleWJvYXJkIA0KOyAgICAgICBkZWxheSAo
dW5saWtlbHkpIHRoZSBjYWxsIHRvIHNvdXQxNiBjb3VsZCBiZSBhcnJhbmdlZCB0byBvY2N1ciBv
bmx5DQo7ICAgICAgIHdoZW4gYSBjaGFuZ2UgaW4gdGhlIHdyaXRlIHJlcXVlc3QgbGluZSBzdGF0
dXMgaGFzIG9jY3VycmVkLiANCjsgICAgICAgVGhlIHdyaXRlIHJlcXVlc3QgbGluZSBpcyBub3Qg
ZXhwbGljaXRseSBkZWJvdW5jZWQgYnV0IGlzIGluIGEgbG9vcCANCjsgICAgICAgd2l0aCBvdGhl
ciBkZWxheXMgYW5kIHNob3VsZCBiZSBlZmZlY3RpdmVseSBkZWJvdW5jZWQuDQoNCjsgICAgICAg
Tm90ZSB0aGF0IHRoZSBCcmVjb3JkaW5nIGZsYWcgaXMgTk9UIGNoYW5nZWQgKGNvZGUgd2hpY2gg
d291bGQNCjsgICAgICAgZG8gdGhpcyBpcyBjb21tZW50ZWQgb3V0KSBhcyB0aGlzIGlzIGFuICJv
cGVyYXRpb25hbCIgYWN0aW9uLg0KDQoJCWpyciAgICAgQnNpbnJlY3JlcSwgc2luZGF0YSwgcHJl
c2V0X2JyZWMgOyBqciBpZiByZWNvcmQgcmVxdWVzdCANCjsgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgaXMgbG93IChhY3RpdmUpDQoJCXNl
dCAgICAgc291dDJwciwgc291dDJuZCAgICAgICAgOyBzZXQgcmVjb3JkIGxpbmUgaGlnaA0KCQlz
ZXQgICAgIHNvdXQybWljb24sIHNvdXQybmQgOyBNaWNyb3Bob25lIG9mZg0KCQlqcCAgICAgIHBy
ZXJlc19icmVjDQoNCjsgIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj
IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjDQoNCnByZXNldF9icmVjICAgICByZXMgICAgIHNv
dXQycHIsIHNvdXQybmQgICAgICAgIDsgc2V0IHJlY29yZCBsaW5lIGxvdyBpZiByZWNvcmRpbmcg
d2FudGVkDQoJCXJlcyAgICAgc291dDJtaWNvbiwgc291dDJuZCA7IE1pY3JvcGhvbmUgb24gDQoN
CjsgQnVnZml4IT86IDMwLjEwLjk3IC0gZG9uJ3QgYWxsb3cgZXh0ZW5kIHRvIGJlIGRlY3JlbWVu
dGVkIHRvIGJlbG93IHplcm8uDQo7ICAgICAgIFRoaXMgd2FzIGhhcHBlbmluZyBvbiBzZXF1ZW50
aWFsIHJlY29yZGluZ3Mgd2hlbiB0aGUgcmVjb3JkIGJ1dHRvbiB3YXMNCjsgICAgICAgaGVsZCBv
biBiZXR3ZWVuIHJlY29yZHMuDQoNCiAgICAgICAgICAgICAgICBsZCAgICAgIGEsIEs2bGV4dGVu
ZCAgICA7IGdldCBleHRlbmQgY291bnQNCiAgICAgICAgICAgICAgICBjcGkgICAgIGEsIDAgICAg
ICAgICAgICA7IGlmIGF0IHplcm8gbGVhdmUgaXQgdGhlcmUNCiAgICAgICAgICAgICAgICBqcnog
ICAgIG5vZGVjDQoNCiAgICAgICAgICAgICAgICBkZWMgICAgIEs2bGV4dGVuZCAgICAgICA7IFRh
a2UgMSBmcm9tIGV4dGVuZCBjb3VudCBhcyBpdCB3aWxsDQogICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgICAgICAgICAgOyBhbHdheXMgY29udGFpbiBhdCBsZWFzdCAxIHByZXNzIHdoZW4g
cmVjb3JkaW5nLiAvIDIwLjguOTcgSzZMIA0KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgIDsgYW5kIGV4dGVuZCBpcyBvbmx5IHJlcXVpcmVkIG9uIDIgb3IgbW9yZSBwcmVz
c2VzLg0Kbm9kZWMNCg0KICAgICAgICAgICAgICAgIGpwICAgICAgcHV0cmVjc3RhdHVzICAgIDsg
SzZMIDIwLjguOTcNCg0KcHJlcmVzX2JyZWMgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDsg
SzZMIDIwLjguOTcNCg0KOyBLNkwgMjAuOC45Nw0KOyAgICAgICBJZiB3ZSBhcmUgaGVyZSBhbnkg
bGV2ZWwtZXh0ZW5kcyBhY2hpZXZlZCBieSByZWNvcmQtYnV0dG9uIHByZXNzaW5nDQo7ICAgICAg
IHNob3VsZCBiZSBjYW5jZWxsZWQgYXMgd2UgYXJlIG5vdCByZWNvcmRpbmcuDQoNCiAgICAgICAg
ICAgICAgICBsZGkgICAgIEs2bGV4dGVuZCwgMCAgICA7IE5vdCByZWNvcmRpbmcgc28gYW55IGV4
dGVuZCBjb3VudCBpcyB6ZXJvZWQgOyBLNkwgMjAuOC45Nw0KDQpwdXRyZWNzdGF0dXMgICAgOyBL
NkwgMjAuOC45Nw0KCQljYWxsICAgIHNvdXQxNg0KCQlsZGkgICAgIHdkciwgd2F0Y2h0aW0gICA7
IGtlZXAgd2F0Y2hkb2cgYXQgYmF5DQoNCjsgPEtLSTQ+ICAgICAgICAgICAgICAgIA0KTGFzdF9D
aGFuY2UNCg0KOyAgICAgICBJdCBhcHBlYXJzIHdlIGFyZSBhbGwgcmVhZHkgdG8gZ28uDQo7ICAg
ICAgIE5vdyB3ZSBvcHRpb25hbGx5IG9mZXIgYSAidXNlciBkZWJvdW5jZSBwZXJpb2QgYmFzZWQg
b24gRGlwU3cgDQo7ICAgICAgIHNldHRpbmdzIHNpbjJkYXRhIGJpdHMgMCB0byAyLiBJZiB0aGVz
ZSBhcmUgbm9uIHplcm8gd2UgZGVsYXkgYnkgDQo7ICAgICAgIGFib3V0IDgwIG1pbGxpc2Vjb25k
cyBwZXIgY291bnQgKDAgdG8gNyBjb3VudHMpIHRoZXJlYnkgb2ZmZXJpbmcgDQo7ICAgICAgIGtl
eSBhY3RpdmF0aW9uIGRlbGF5cyBvZiB1cCB0byA3IHggODBtcyA9IDU2MCBtaWxsaXNlY29uZHMu
DQo7ICAgICAgIFRoZSBMRUQgaXMgbGl0IGF0IHRoZSBzdGFydCBvZiB0aGlzIHBlcmlvZCBzbyB0
aGF0IHVzZXJzIGNhbg0KOyAgICAgICBzZWUgdGhhdCB0aGVpciBrZXlwcmVzcyBpcyBhY3R1YWxs
eSBhY2hpZXZpbmcgc29tZXRoaW5nLg0KDQoJCWxkICAgICAgYSwgc2luMmRhdGEgICAgIDsgZ2V0
IERpcFN3aXRjaCBzZXR0aW5ncw0KCQlhbmRpICAgIGEsIDA3aCAgICAgICAgICA7IGtlZXAgb25s
eSAzIGxzYidzDQoJCWpybnogICAgdXNlcl9kZWxheSAgICAgIDsganIgaWYgdXNlciBkZWxheSBp
cyB3YW50ZWQNCgkJanAgICAgICBub19kZWxheSAgICAgICAgOyBqcCBpZiBubyBkZWxheQ0KDQo7
ICMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj
IyMjIyMjIyMjIyMjIw0KDQp1c2VyX2RlbGF5DQoNCjsgPEtLSTUgZ3JlYXRseSByZW1vZGVsbGVk
IHRvIHVzZSBpcnEgdGltZXJ1ZCA+DQoNCjsgICAgICAgRGVsYXkgZm9yIHVzZXIgc2VsZWN0ZWQg
cGVyaW9kDQoNCgkJbGQgICAgICB1ZF90ZW1wLCBhICAgICAgOyBzYXZlIGRlbGF5IHZhbHVlDQoJ
CXNsYSAgICAgYSAgICAgICAgICAgICAgIDsgZG91YmxlIGl0DQoJCWFkZCAgICAgYSwgdWRfdGVt
cCAgICAgIDsgYWRkIHRvIGluaXRpYWwgdmFsdWUgLS0+IDMgeCBtdWx0DQoJCWxkICAgICAgdWRf
dGVtcCwgYSAgICAgIDsgc2F2ZSB0cmlwbGVkIHZhbHVlDQoJCQ0KCQlzZXQgICAgIHNvdXQybGVk
LCBzb3V0Mm5kIDsgc2hvdyB0aGF0IHNvbWV0aGluZyBpcyBoYXBwZW5pbmcuDQoJCWNhbGwgICAg
c291dDE2ICAgICAgICAgIA0KCQkNCgkJbGQgICAgICBhLCB1ZF90ZW1wICAgICAgOyBnZXQgdHJp
cGxlZCB2YWx1ZQ0KCQlsZCAgICAgIHRpbWVydWQsIGEgICAgICA7IHNldCBpcnEgdGltZXIgdG8g
TiB4IDMgeCAzNy41bXMNCgkJbGQgICAgICB0aW1lcnVkLCBhICAgICAgOyA9IE4geCAwLjExMjUg
c2Vjb25kcw0KDQo7ICAgICAgIFdlIHdpbGwgbm93IGxvb3Agd2hpbGUgdGhlIHNhbWUga2V5IGlz
IGhlbGQgZG93biB1bnRpbCBlaXRoZXINCjsgICAgICAgdGhlIHVzZXIgcmVsZWFzZXMgdGhlIGtl
eSBvciB0aGUgInRyZW1vciIgZGVsYXkgdGltZXMgb3V0Lg0KOyAgICAgICBUaGVyZSBhcmUgMiBw
YXRocyB0aHJvdWdoIHRoaXMgbG9vcCB0byBhY2NvdW50IGZvciBib3RoIGludGVybmFsDQo7ICAg
ICAgIGFuZCByZW1vdGUga2V5Ym9hcmRzLiANCg0KdWRfbG9vcCAgICAgICAgICAgICAgICANCgkJ
anJzICAgICBsb2NhbCwga2V5bW9kZSwgdWQyX2xvb3AgICA7IGIgaWYgbWFpbiBrZXlib2FyZA0K
DQoJOyBIZXJlIGlmIHJlbW90ZSBrZXlib2FyZA0KDQoJCWNhbGwgICAgU0lONCAgICAgICA7KSBS
ZW1vdGUgS2JkIHRlc3RpbmcNCgkJY2FsbCAgICBTSU5LRVkgICAgIDspIFJlbW90ZSBLYmQgdGVz
dGluZw0KCQlqcCAgICAgIHVkM19sb29wICAgOykgUmVtb3RlIEtiZCB0ZXN0aW5nDQoNCgk7ICoq
KioqKioqKioqDQoNCgk7IE1haW4ga2V5Ym9hcmQNCg0KejkwOA0KdWQyX2xvb3AgICAgICAgIGNh
bGwgICAgS0VZSU4gICAgICAgICAgIDsgR2V0IHByZXNlbnQga2V5IHZhbHVlDQoJDQoJOyBCb3Ro
IGtleWJvYXJkcyAgICAgICAgICAgICAgICANCg0KdWQzX2xvb3AgICAgY3AgICAgICBhLCByYXdr
ZXljb2RlICAgOyBhbmQgc2VlIGlmIHVzZXIgaGFzIHBlcnNpc3RlZA0KCQlqcm56ICAgIGJhY2tf
b2ZmICAgICAgIDsganIgaWYgbm90IHNhbWUga2V5LCB1c2VyIGhhcyBnaXZlbiB1cA0KCQkNCgkJ
bGQgICAgICBhLCB0aW1lcnVkICAgICAgOyBjaGVjayB0aW1lciBmb3IgZXhwaXJ5DQoJCWpyeiAg
ICAgR29NYW5HbyAgICAgICAgIDsganIgLyBnbyBmb3IgU1JCIGlnbml0aW9uIG9uIHRpbWVyIGV4
cGlyeQ0KCQlqcCAgICAgIHVkX2xvb3AgICAgICAgICA7IGpwIC8gc3RpbGwgc2FtZSBrZXkgcHJl
c3NlZCBzbyBmYXIuICAgICAgICAgDQoJCQ0KOyAjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj
IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIw0KDQoNCgkJOyBzYW1lIGtleSBu
b3QgcHJlc3NlZCwgbWFpbiBlbmdpbmUgc2h1dGRvd24gICAgICAgICAgICAgICAgDQpiYWNrX29m
ZiAgICAgICAgICAgICAgICANCgkJcmVzICAgICBzb3V0MmxlZCwgc291dDJuZCA7IHNob3cgdGhh
dCBzb21ldGhpbmcgc3RvcHBlZCBoYXBwZW5pbmcuDQoJCWNhbGwgICAgc291dDE2ICAgICAgICAg
IA0KDQogICAgICAgICAgICAgICAganAgICAgICBub19rZXkNCg0KOyAjIyMjIyMjIyMjIyMjIyMj
IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMNCg0K
R29NYW5HbyAgICAgICAgIDsgKG5vdGUgdGhhdCBMRUQgaXMgb24pDQoNCm5vX2RlbGF5ICAgICAg
ICA7IGxpZnRvZmYNCg0KOyA8S0tJNCBlbmQ+DQo7IDxLS0k1IHN0YXJ0Pg0KOyAgICAgICBCcmll
Zmx5IGZsYXNoIExFRCB0byBzaG93IHJlY29yZCBzdGFydC4gDQoJCQ0KCQlyZXMgICAgIHNvdXQy
bGVkLCBzb3V0Mm5kICAgICAgIDsgTEVEIG9mZg0KCQljYWxsICAgIHNvdXQxNg0KCQlsZGkgICAg
IGEsIDAxNGggICAgICAgICAgICAgICAgIDsgZm9yIDUwIG1zDQoJCWNhbGwgICAgc2RlbGF5DQoJ
CXNldCAgICAgc291dDJsZWQsIHNvdXQybmQgICAgICAgOyBhbmQgb24gYWdhaW4NCgkJY2FsbCAg
ICBzb3V0MTYNCjsgPEtLSTUgZW5kPg0KDQoNCjsgKioqKioqKioqKioqKioqKioqKioqKioqKioq
KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqDQo7DQo7ICAgICAgIEEgc3RhYmxlIHZh
bGlkIGtleXByZXNzIGhhcyBiZWVuIGRldGVjdGVkLiANCjsgICAgICAgVGhpcyBpcyB0aGUgc3Rh
Z2UgYXQgd2hpY2ggd2UgYXJlIGNvbW1pdHRlZCB0byBhY3Rpb24gZHVlIHRvIGEga2V5DQo7ICAg
ICAgIGhhdmluZyBiZWVuIHByZXNzZWQuIFRoaXMgY29kZSB3aWxsIGJlIHByb2Nlc3NlZCB0byB0
dXJuIGl0IGludG8gDQo7ICAgICAgIGFuIElTRCBhZGRyZXNzIGJhc2VkIG9uIGtleW1hcHBpbmcg
ZGlwc3dpdGNoIHNldHRpbmdzIGFuZCB0aGVuIGFjdGlvbiANCjsgICAgICAgd2lsbCBiZSB0YWtl
biBiYXNlZCBvbiB3aGV0aGVyIHdlIGFyZSBpbiByZWNvcmQsIHBsYXkgb3IgcmVwZWF0LXBsYXkg
DQo7ICAgICAgIG1vZGUuDQogICAgICAgIA0KCQlsZCAgICAgIGEsIHJhd2tleWNvZGUgICA7IGdl
dCB2YWxpZGF0ZWQga2V5Y29kZQ0KCQlhbmRpIGEsIDFGSCAgICAgICAgICAgICA7IHVzZSBvbmx5
IDUgbG93ZXIgYml0cw0KCQ0KCTsgQ2hhbmdlIGNvZGUgdG8gbWF0Y2ggYmluYXJ5IGtleSBudW1i
ZXJzICAgICAgICAgICAgICAgIA0KCQ0KCQlsZGkgZHJ3ciwga2V5bWFuZ2xlLncgICA7IHBvaW50
IHRvIGxvb2t1cCB0YWJsZQ0KCQlsZGkgeCwga2V5bWFuZ2xlLmQgICAgICA7Lg0KCQlhZGQgYSwg
eA0KCQlsZCB4LCBhDQoJCWxkIGEsICh4KQ0KICAgICAgICAgICAgICAgIGxkICAgICAgVmtleWNv
ZGUsIGEgICAgIDsgc2F2ZSBtb2RpZmllZCBrZXljb2RlDQoNCgk7IEEgbm93IGNvbnRhaW5zIGEg
NSBiaXQga2V5IG51bWJlciAgICAgICAgICAgICAgICANCgk7IFRyYW5zbGF0ZSBrZXljb2RlIGlu
dG8gc3BlZWNoIGFkZHJlc3MgDQoJOyBPcmlnaW5hbCBBIGlzIGRlc3Ryb3llZA0KICAgICAgICA7
IFJlc3VsdHMgYXJlIGluIHRhbGthZGhpICYgdGFsa2FkbG8gKHJhdyBjb2RlcykgJiB0YWxrZHVy
biAoc2xpZ2h0bHkgcHJvY2Vzc2VkKQ0KDQoJCWNhbGwgICAga2V5bWFwICAgICAgICAgIDsgVHJh
bnNsYXRlIGNvZGUgaW4gQSB0byBhZGRyZXNzDQogICAgICAgICAgICAgICAgICAgICAgICANCjsg
PEtLSjNHPiAtIHVzZSB0YWxrZHVybiB0byBjb250cm9sIHNsZWVwIHRpbWluZw0KOw0KOyAgICAg
ICBBcyBhIGtleSBoYXMgYmVlbiBwcmVzc2VkIHJlc2V0IHNsZWVwIHRpbWVyIHRvIHN0b3AgSVNE
IGdvaW5nIHRvIA0KOyAgICAgICBzbGVlcC4gIA0KOw0KOyAgICAgICBBcyB0aGUgdGFsayBkdXJh
dGlvbiB2YWx1ZSBpcyBhIGRpcmVjdCBtdWx0aXBsZSBvZiB0aGUgDQo7ICAgICAgIHRpbWVyX3Bk
IGludGVydXB0IGRlbGF5IG9mIDMuNzVzIHdoZW4gaXRzIHZhbHVlIGlzIDBjaCBvciBsZXNzIGl0
DQo7ICAgICAgIG1heSBiZSB1c2VkIHRvIHNldCB0aW1lcl9wZCB3aGVuIGtleSBkZWxheXMgYXJl
IGxvbmcuIElmIHRoaXMgaXMgbm90IA0KOyAgICAgICBkb25lIHRpbWVyLXBkIG1heSB0aW1lIG91
dCBhbmQgcHV0IHRoZSBzeXN0ZW0gdG8gc2xlZXAsIGJlZm9yZSANCjsgICAgICAgdGFsa2luZyBp
cyBmaW5pc2hlZC4gDQoNCgkJbGQgICAgICBhLCB0YWxrZHVybg0KICAgICAgICA7IEZBTExUSFJP
VUdIIDk3MDgxMyAgICAgICAgICAgICAgICAgY3BpICAgICBhLCAwY2gNCiAgICAgICAgOyBLNjog
IEFMV0FZUyBKVU1QICBqcmMgICAgIHZhcl9wZCAgOyBqciBpZiBiaWcga2V5IC0gc2V0IHBkIGRl
bGF5IHVzaW5nIHRhbGtfZHVybg0KICAgICAgICA7IEs2TDogQWx3YXlzIGp1bXAgYWxzbw0KDQog
ICAgICAgIDsgRkFMTCBUSFJPVUdIIDk3MDgxMyAgICAgICAgICAgICAganAgICAgICB2YXJfcGQg
IDsgYWx3YXlzIHVzZSB0YWxrZHVybiBhcyB0aW1lcjIgdGlja3Mgb2YgMy43NXMNCg0KdmFyX3Bk
ICAgICAgICAgICAgICAgIA0KCTsgVXNlIHZhcmlhYmxlIHBvd2VyIGRvd24gZGVsYXkNCg0KOyBL
Nkw6IFRoaXMgaXMgcnViYmlzaCBmb3IgYSBLNkwgLSB3aWxsIG5lZWQgdG8gd29yayBvbiBmaW5h
bCBrZXkgdGltZXIgdmFsdWUuDQoNCg0KCQlpbmMgICAgIGEgICAgICAgOyBNYWtlIHRoZSBkZWxh
eSBhIGxpdHRsZSBsYXJnZXIgdG8gYXZvaWQgDQoJCWluYyAgICAgYSAgICAgICA7IGNsaXBwaW5n
IHRoZSBlbmQgb2Ygc3BlZWNoLiANCg0KOyBNT0RJRklDQVRJT04gTkVFREVEDQo7IEs2TCB0ZW1w
b3JhcnkNCg0KICAgICAgICAgICAgICAgIGpycyAgICAgQms2bCwga2V5bW9kZSwgazZsdGltZXJw
ZCAgIDsgaiBpZiBhIEs2TA0KICAgICAgICAgICAgICAgIGpwICAgICAgazZ0aW1lcnBkDQprNmx0
aW1lcnBkDQoNCjsgICAgICAgZ2V0IGtleWxldiBkZWxheSBmbGFnIA0KDQogICAgICAgICAgICAg
ICAgbGQgICAgICBhLCB0YWxrZHVybg0KICAgICAgICAgICAgICAgIGFuZGkgICAgYSwgMDAwMDAw
MDFiICAgIDsgMTYuOC45Nw0KDQo7ICAgICAgIGNvbnZlcnQgdG8gZWl0aGVyIDMyIGtleSBtb2Rl
ID0gMSBvciBhbGwgb3RoZXJzID0gMg0KDQogICAgICAgICAgICAgICAgYWRkaSAgICBhLCAwMSAg
IDsgYmVjb21lcyAxIGZvciAzMiBrZXkgbW9kZSBhbmQgMiBmb3IgYWxsIG90aGVycw0KICAgICAg
ICAgICAgICAgIGxkICAgICAgdiwgYSAgICA7IHB1c2ggZGVsYXkNCg0KOyAgICAgICBhZGQgMSBl
eHRyYSBsZXlsZXYgZGVsYXkgcGVyIGV4dGVuZCBjb3VudA0KDQogICAgICAgICAgICAgICAgY3Bp
ICAgICBhLCAxICAgICAgICAgICAgOyBJZiBjbnQgaXMgb25lIHdlIGFyZSBpbiAzMiBrZXkgbW9k
ZSwNCiAgICAgICAgICAgICAgICBqcnogICAgIGFkZG9uY2UgICAgICAgICA7IGogaWYgaW4gMzIg
a2V5IG1vZGUgdG8gYWRkIDEgdGljaw0KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgIDsgcGVyIGV4dGVuZF9jb3VudA0KDQogICAgICAgICAgICAgICAgYWRkICAgICBhLCBL
NmxleHRlbmQgICAgOyBlbHNlIGFkZCBhbiBleHRyYSBleHRlbmQgY291bnQgcGVyIGV4dGVuZF9s
ZXZlbA0KYWRkb25jZQ0KICAgICAgICAgICAgICAgIGFkZCAgICAgYSwgSzZsZXh0ZW5kICAgIDsg
YWRkIGFnYWluIChvciBvbmNlIGluIDMyIGtleSBtb2RlKQ0KDQogICAgICAgICAgICAgICAgbGQg
ICAgICBLNmxyZWN0aW1lLCBhICAgOyBzYXZlIEs2TCByZWNvcmRpbmcgZGVsYXkgZm9yIGxhdGVy
IHVzZS4NCiAgICAgICAgICAgICAgICBpbmMgICAgIGEgICAgICAgICAgICAgICA7IGV4dGVuZCB0
aW1lIGZvciBzaHV0IGRvd24gDQogICAgICAgICAgICAgICAgaW5jICAgICBhDQprNnRpbWVycGQN
Cg0KOyAgICAgICBCdWdmaXggKGFjdHVhbGx5IGJ1ZyBieXBhc3MpIDI4LjguOTcgMTAzMCBpc2gN
CjsgICAgICAgVGhlIHNwZWFraW5nIHRpbWUgZm9yIGV4dGVuZGVkIGtleXMgaXMgbGVzcyB0aGFu
IHRoZSBSRUNPUkRFRCB0aW1lLg0KOyAgICAgICBUaGlzIGNhbiBiZSBjb25maXJtZWQgYnkgcmVj
b3JkaW5nIG9uIGxldmVsIDEgd2l0aCBvbmUgZXh0ZW5kIHNvIHRoYXQNCjsgICAgICAgYSBtZXNz
YWdlIGZpbGxzIG1vc3Qgb2YgbGV2ZWwgMSBhbmQgbGV2ZWwgNC4gV2hlbiB0aGUgbWVzc2FnZSBp
cyBwbGF5ZWQNCjsgICAgICAgYmFjaywgc29tZSBpcyBtaXNzaW5nLiBIb3dldmVyLCBpZiBsZXZl
bCA0IGlzIHBsYXllZCB0aGUgdGFpbCBvZiB0aGUNCjsgICAgICAgbWVzc2FnZSBpcyBoZWFyZC4g
Q29uY2x1ZGU6IFRoYXQgdGltZXJfcGQgaXMgc2h1dHRpbmcgc3BlZWNoIGRvd24gZWFybHkuDQo7
ICAgICAgIElGIHRoaXMgaXMgd2hhdCBpcyB3cm9uZywgcmF0aGVyIHRoYW4gZmluZGluZyBvdXQg
d2h5LCBmaXggaXQgImZvciBub3ciDQo7ICAgICAgIGJ5IGRvdWJsaW5nIHRoZSB0aW1lIHByb3Zp
ZGVkLg0KOyAgICAgICBOT1RFOiBJbnZlc3RpZ2F0aW9uIHNob3dzIHRoYXQgdGhlIHRpbWUgc3Bv
a2VuIGZvciB2YXJpZXMgKGJ1dCBpcw0KOyAgICAgICBhbHdheXMgbGVzcyB0aGFuIHRoZSBjb3Jy
ZWN0IHRpbWUpLiBUaGlzIE1BWSBiZSBkdWUgdG8gdGhlIGFzeW5jaHJvbm91cw0KOyAgICAgICBk
ZWNyZW1lbnRpbmcgb2YgdGltZXJfcGQgcmVsYXRpdmUgdG8gb3RoZXIgdGltZXJzIGFzIHRpbWVy
X3BkIHNoYXJlcw0KOyAgICAgICBhbiBpbnRlcnVwdCBkcml2ZW4gcHJlc2NhbGVyLg0KOyAgICAg
ICBHT1RDSEEgKEkgdGhpbmspLiBDbGVhcmluZyB0aW1lcjJ6IHByZXNjYWxlciBzZWVtcyB0byBt
YWtlIGl0IHdvcmsgQU9LLg0KDQoNCg0KICAgICAgICAgICAgICAgIFNMQSAgICAgQSAgICAgICAg
ICAgICAgIDsgZG91YmxlIG1heCBhbGxvd2FibGUgc3BlYWtpbmcgdGltZS4NCiAgICAgICAgICAg
ICAgICBsZCAgICAgIHRpbWVyX3BkLCBhICAgICA7IHNhdmUgZGVsYXkgdG8gc2h1dCBkb3duIHRp
bWVyLg0KCSAgICAgICAgICBsZCAgICAgIHRpbWVyX3BkLCBhDQogICAgICAgICAgICAgICAgY2xy
ICAgICB0aW1lcjJ6ICAgICAgICAgOyBDbGVhciBwcmVzY2FsZXIgLSBLNkxCMiA5NzA4MjggDQoN
CgkgICAgICANCjsgICAgICAgICAgICAgICAgICAgICAgIC49Lj0uPS49Lj0uPS49Lj0NCg0KYXRs
YXN0DQoNCjsgICAgICAgQXQgbGFzdCwgbXkgYWRkcmVzcyBpcyB3aG9sZSBhZ2FpbiAhDQo7ICAg
ICAgIElTRCBzbG90IGFkZHJlc3MgaXMgaW4gdGFsa2FkaGkvdGFsa2FkbG8NCjsgICAgICAgTm93
IHdlIG5lZWQgdG8gZGVjaWRlIHdoYXQgdG8gZG8gd2l0aCBpdC4NCjsNCjsgQ2hvaWNlcyBhcmUg
LSANCjsNCjsgICAgICAgQ09OVFJPTA0KOyAgICAgICBBZGRlZCBhdCBLNkwNCjsNCjsgICAgICAg
ICAgICAgICBLZXkgbWF5IG5ldmVyIGdldCBhcyBmYXIgYXMgc3BlYWtpbmcNCjsNCjsgICAgICAg
UkVDT1JEDQo7ICAgICAgICAgICAgICAgUmVjb3JkaW5nIGNvbnRpbnVlcyB3aGlsZSB0aGUgc2Ft
ZSBrZXkgcmVtYWlucyBwcmVzc2VkIGFuZCANCjsgICAgICAgICAgICAgICB0aGUgdGltZSBhbGxv
dHRlZCB0byB0aGUga2V5IGlzIG5vdCBleGNlZWRlZC4gQSBwZXJpb2Qgb2YgDQo7ICAgICAgICAg
ICAgICAga2V5dXAgaXMgcmVxdWlyZWQgYmVmb3JlIHRoZSBuZXh0IGtleSBjYW4gYmUgcHJvY2Vz
c2VkDQo7DQo7ICAgICAgICAgICAgICAgICAgICAgICBDYWxjdWxhdGUgJiBvdXRwdXQgYWRkcmVz
cywgbG93ZXIgSVNEL1BSLg0KOyAgICAgICAgICAgICAgICAgICAgICAgTG93ZXIgSVNEL0NTDQo7
ICAgICAgICAgICAgICAgICAgICAgICBTdGFydCBrZXkgZHVyYXRpb24gdGltZXINCjsgICAgICAg
ICAgICAgICAgICAgICAgID8gTEVEIG9uID8NCjsgICAgICAgICAgICAgICAgICAgICAgIFdoaWxl
IGtleSBkb3duICAtIA0KOyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBsZWF2ZSBJU0Qv
Q1MgZG93bg0KOyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBpZiB0aW1lciBleHBpcmVz
IA0KOyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFJhaXNlIElTRC9DUyAN
CjsgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBpZGxlIGxvb3AgdW50aWwg
a2V5dXANCjsgICAgICAgICAgICAgICAgICAgICAgIEtleXVwICAgICAgICAgICAtIFJhaXNlIElT
RC9DUw0KOyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIC0gcHVsc2UgSVNE
L1BEIGhpL2xvDQo7DQo7ICAgICAgIFBMQVkgLSBObyBSZXBlYXQNCjsNCjsgICAgICAgICAgICAg
ICBBIHNpbmdsZSBsb3cgcHVsc2Ugb2YgQ1MgaXMgcHJvdmlkZWQuIEEga2V5IHdoaWNoIGlzIGhl
bGQgb24gDQo7ICAgICAgICAgICAgICAgd2lsbCBpZGxlIGxvb3AgdW50aWwgcmVsZWFzZWQuIFRv
IGluaXRpYXRlIGFub3RoZXIgc2VxdWVuY2UgDQo7ICAgICAgICAgICAgICAgdGhlIG5leHQga2V5
IG11c3QgYmUgcHJlc3NlZCBhZnRlciB0aGUgY3VycmVudCBzZXF1ZW5jZSANCjsgICAgICAgICAg
ICAgICBmaW5pc2hlcy4gDQo7DQo7ICAgICAgICAgICAgICAgICAgICAgICBDYWxjdWxhdGUgJiBv
dXRwdXQgYWRkcmVzcw0KOyAgICAgICAgICAgICAgICAgICAgICAgUHVsc2UgSVNEL1BEIGhpL2xv
IChyZXNldHMgYW55IHByaW9yIGxvY2t1cCkNCjsgICAgICAgICAgICAgICAgICAgICAgIFB1bHNl
IElTRC9DUyBsby9oaQ0KOyAgICAgICAgICAgICAgICAgICAgICAgV2hpbGUga2V5IGRvd24gICAt
IGlkbGUgbG9vcA0KOw0KOyAgICAgICBQbGF5IC0gUmVwZWF0ICAgQ2FsY3VsYXRlICYgb3V0cHV0
IGFkZHJlc3MNCjsNCjsgICAgICAgICAgICAgICBNb25pdG9yaW5nIG9mIEVPTS9PVkYgaXMgbmVl
ZGVkLiBXaGVuIGEga2V5IGlzIGZvdW5kIHRvIGJlIA0KOyAgICAgICAgICAgICAgIGhlbGQgZG93
biB3aGVuIGEgc2VxdWVuY2UgdGVybWluYXRlcyBhIG5ldyBDUyBsb3cgcHVsc2UgaXMgDQo7ICAg
ICAgICAgICAgICAgaW5pdGlhdGVkLiBQZXJtYW5lbnQgb3V0cHV0IG9mIENTIHdvdWxkIG5vdCBi
ZSBhZGVxdWF0ZSBhcyANCjsgICAgICAgICAgICAgICB0aGUgZm9sbG93aW5nIG1lc3NhZ2Uocykg
d291bGQgYmUgc2VxdWVudGlhbGx5IHNlbGVjdGVkLg0KOyAgICAgICAgICAgICAgICAgICAgDQo7
ICAgICAgICAgICAgICAgICAgICAgICBMb3dlciBJU0QvQ1MNCjsgICAgICAgICAgICAgICAgICAg
ICAgID8gTEVEIG9uID8NCjsgICAgICAgICAgICAgICAgICAgICAgIFB1bHNlICBJU0QvQ1MgbG8v
aGlkb3duDQo7ICAgICAgICAgICAgICAgICAgICAgICBXaGlsZSBrZXkgZG93biAgLSANCjsgICAg
ICAgICAgICAgICAgICAgICAgICAgICAgICAgaWYgRU9NIGxvdyBnb2luZyBlZGdlICANCjsgICAg
ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBXYWl0IHRpbGwgRU9NIGdvZXMgaGln
aA0KOyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFB1bHNlIElTRC9DUyBs
by9oaQ0KOyAgICAgICAgICAgICAgICAgICAgICAgS2V5dXAgICAgICAgICAgIFB1bHNlIElTRC9Q
RCBoaS9sbw0KOw0KDQo7ID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PQ0KOw0KOyAgICAg
ICBGaXJzdCBzb21lIGluaXRpYWxpc2F0aW9uIG9mIGZsYWdzIHdoaWNoIHdpbGwgYmUgdXNlZCB0
byBkZXRlcm1pbmUgdGhlIA0KOyAgICAgICBwcm9wZXIgYWN0aW9uLg0KDQo7IDEuDQo7ICAgICAg
IEZpbmQgb3V0IGlmIHRoZSB1c2VyIGlzIGF0dGVtcHRpbmcgdG8gcmVjb3JkLg0KOyAgICAgICBz
ZXQgIkJyZWNvcmRpbmciIGlmIHVzZXIgd2lzaGVzIHRvIHJlY29yZC4NCjsgICAgICAgTm90ZSBm
bGFncyBpcyAxIG9uIHJlY29yZCBidXQgcmVxdWVzdCBsaW5lIGlzIGxvdyBvbiByZWNvcmQNCg0K
CQlqcnIgICAgIEJzaW5yZWNyZXEsIHNpbmRhdGEsIHNldF9icmVjIDsganIgaWYgcmVjb3JkIHJl
cXVlc3QgDQo7ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgIGlzIGxvdyAoYWN0aXZlKQ0KCQlyZXMgICAgIEJyZWNvcmRpbmcsIGZsYWdzIDsgcmVx
cmVzIGhpZ2ggLSBub3QgcmVjb3JkaW5nDQoJCWpwICAgICAgcmVzX2JyZWMNCg0KOyAjIyMjIyMj
IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj
IyMjIyMNCg0KOyB6enp6MQ0Kc2V0X2JyZWMgICAgICAgIHNldCAgICAgQnJlY29yZGluZywgZmxh
Z3MgOyByZXFyZXMgbG93ICAtIGluZGljYXRlcyByZWNvcmRpbmcgaXMgcmVxdWlyZWQNCnJlc19i
cmVjDQo7DQpvbnRoZWZseQ0KOyAgICAgICAgICAgICAgICJPTiBUSEUgRkxZIiBrZXkgcHJvY2Vz
c2luZw0KOw0KOyAyLlggLSBBZGRlZCBhdCBLNkwgLSBzZWUgaWYgdGhpcyBpcyBhbiAib24gdGhl
IGZseSIgY29udHJvbCBmdW5jdGlvbi4NCjsNCjsgVGhlICJvdGYiIGNvbnRyb2xzIGFyZToNCjsg
ICAgICAgOS44Ljk3OiAgQ2hhbmdpbmcgb2YgbGV2ZWxzICAgICBpbiAzMiBrZXkgbW9kZS4NCjsg
ICAgICAgMy45Ljk3OiAgU2luZ2xlIGtleSByb3RhdGluZyBsZXZlbCBjaGFuZ2UuDQo7ICAgICAg
IDMuOS45NzogICAgICAgICAgICAgICAgICAgICAgICAgYW5kIGluIDE2IGtleSBtb2RlDQo7IFRo
ZXNlIHdpbGwgYmUgZmFpcmx5IGhhcmQgY29kZWQgaGVyZS4NCjsgTGF0ZXIgb24gbW9yZSBnZW5l
cmFsaXR5IHdpbGwgYmUgcmVxdWlyZWQuDQoNCjsgMzIga2V5IG1vZGUgbGV2ZWwgc2V0dGluZyBm
cm9tIGtleWJvYXJkDQoNCiAgICAgICAganJyICAgICBCazZsLCBrZXltb2RlLCBub3RvdGYzMiAg
ICAgICAgIDsgai9ieXBhc3MgaWYgbm90IEs2TA0KICAgICAgICBqcnMgICAgIEJyZWNvcmRpbmcs
IGZsYWdzLCBub3RvdGYzMiAgICAgOyBqL2J5cGFzcyBpZiByZWNvcmRpbmcgYXMgY2FuJ3QgYmUg
Y2hhbmdpbmcgbGV2ZWwuDQogICAgICAgIGpycyAgICAgQjMya2V5LCBrZXltb2RlLCB0ZXN0b3Rm
MSAgICAgICA7IGogdG8gb3RmIGlmIGluIDMyIGtleSBtb2RlLg0KICAgICAgICBqcnMgICAgIEIx
NmtleSwga2V5bW9kZSwgdGVzdG90ZjEgICAgICAgOyBqIHRvIG90ZiBpZiBpbiAxNiBrZXkgbW9k
ZS5kZS4NCg0KICAgICAgICBqcCAgICAgIG5vdG90ZjMyDQoNCnRlc3RvdGYxDQoNCjsgICAgICAg
SWYgaGVyZSwgd2UgYXJlIGluIDMyIG9yIDE2dyBrZXltb2RlIGFuZCBub3QgcmVjb3JkaW5nLg0K
OyAgICAgICBTZWUgaWYgdGhlIGtleSBwcmVzc2VkIGlzIGEgbGV2ZWwgc2hpZnQga2V5Lg0KOyAg
ICAgICBMUyBrZXlzIGFyZSBjdXJyZW50bHkgaW4gdGhlIExIIGNvbHVtbiBvZiA0IGtleXMuDQo7
ICAgICAgIENvZGVzIChhZnRlciBrZXltYXApIGFyZSAwMGgsIDA0aCwgMDhoLCAwQ2guDQo7ICAg
ICAgIFRvIHRlc3QgdGhlIGxldmVsIGtleXMgYWdhaW5zdCB0aGUgY3VycmVudCBsZXZlbCB0aGVz
ZSBuZWVkDQo7ICAgICAgIHRvIGJlIHRyYW5zbGF0ZWQgaW50byB0aGUgbGV2ZWxzIDAsMSwyLDMu
DQo7ICAgICAgIFdoaWxlICJjbGV2ZXIiIGNvZGluZyBjb3VsZCBiZSB1c2VkIHRoZSBlYXNpZXN0
IG1ldGhvZCBpcyBhbg0KOyAgICAgICBleHBsaWNpdCB0ZXN0IGFuZCBzZXQgZm9yIGVhY2ggdmFs
dWUuDQo7ICAgICAgICAgICAgICANCg0KOyAiQXMgaXQgaGFwcGVucyIgdGhlIGtleSBjb2RlcyBv
dXRwdXQgYnkgS2V5bWFuZ2xlIGFyZSBpZGVudGljYWwgdG8NCjsgdGhvc2UgdXNlZCBoZXJlIHNv
IHRoZSB0cmFuc2xhdGlvbiBpcyB1bi1uZWVkZWQgU08gRkFSIGJ1dCBmb3IgZ2VuZXJhbGl0eQ0K
OyBsZWF2ZSBpdCBpbiBzbyB3ZSBjYW4gbWFrZSBjaGFuZ2UgZWFzaWx5Lg0KDQogICAgICAgICAg
ICAgICAgbGQgICAgICBhLCBWa2V5Y29kZSAgICAgICAgICAgICA7IGdldCBzYW5pdGlzZWQgaW5w
dXQga2V5IGNvZGUNCiAgICAgICAgICAgICAgICBhbmRpICAgIGEsIDAwMDExMTExYiAgICAgICAg
ICAgIDsgZW5zdXJlIG9ubHkgNSBsc2JzIHVzZWQNCg0KOyBJZiBhICJyZWFsIiB0cmFuc2xhdGlv
biB3YXMgaGFwcGVuaW5nIHRoZSBrZXljb2RlcyB0byBiZSB0cmFuc2xhdGVkIHdvdWxkDQo7IGFw
cGVhciBpbiB0aGUgZm9sbG93aW5nIGxpbmUgZWcgIGNwaSBhLCJrZXljb2RlIg0KOyBUaGUga2V5
Y29kZXMgZnJvbSBrZXltYW5nbGUgc3RhcnQgYXQgIjAwIiBpbiB0aGUgYm90dG9tIGxoIGNvcm5l
ciBhbmQNCjsgaW5jcmVtZW50IGJ5IHJvdyBhbmQgdGhlbiBieSBjb2x1bW4uDQoNCiAgICAgICAg
ICAgICAgICBjcGkgICAgIGEsIDAwaCAgICAgICAgICAgICAgICAgIDsgS2V5ID0gMDA/DQogICAg
ICAgICAgICAgICAganJueiAgICBub3QwYSAgICAgICAgICAgICAgICAgICA7IGogaWYgbm90IGtl
eSAwMA0KICAgICAgICAgICAgICAgIGxkaSAgICAgYSwgMDBoICAgICAgICAgICAgICAgICAgOyBl
bHNlIHRyYW5zbGF0ZSB0byBlcXVpdmFsZW50IHNoaWZ0IGtleQ0KICAgICAgICAgICAgICAgIGpw
ICAgICAgbHNoaWZ0MDEgICAgICAgICAgICAgICAgOyBhbmQgZ28gdG8gc2hpZnQgcHJvY2Vzc2lu
Zy4gDQpub3QwYQ0KICAgICAgICAgICAgICAgIGNwaSAgICAgYSwgMDFoICAgICAgICAgICAgICAg
ICAgOyBTYW1lIGFzIGFib3ZlIGZvciBvdGhlciBzaGlmdCBrZXlzDQogICAgICAgICAgICAgICAg
anJueiAgICBub3QwYg0KICAgICAgICAgICAgICAgIGxkaSAgICAgYSwgMDENCiAgICAgICAgICAg
ICAgICBqcCAgICAgIGxzaGlmdDAxDQpub3QwYg0KICAgICAgICAgICAgICAgIGNwaSAgICAgYSwg
MDJoICAgICAgICAgICAgICAgICAgOyBTYW1lIGFzIGFib3ZlIGZvciBvdGhlciBzaGlmdCBrZXlz
DQogICAgICAgICAgICAgICAganJueiAgICBub3QwYw0KICAgICAgICAgICAgICAgIGxkaSAgICAg
YSwgMDJoDQogICAgICAgICAgICAgICAganAgICAgICBsc2hpZnQwMQ0Kbm90MGMNCiAgICAgICAg
ICAgICAgICBjcGkgICAgIGEsIDAzaCAgICAgICAgICAgICAgICAgIDsgU2FtZSBhcyBhYm92ZSBm
b3Igb3RoZXIgc2hpZnQga2V5cw0KICAgICAgICAgICAgICAgIGpybnogICAgbm90MGQNCiAgICAg
ICAgICAgICAgICBsZGkgICAgIGEsIDAzaA0KICAgICAgICAgICAgICAgIGpwICAgICAgbHNoaWZ0
MDINCm5vdDBkDQogICAgICAgICAgICAgICAganAgICAgICBub3RvdGYzMg0KDQo7ICAgICAgICoq
KioqKioqKioqKioqKioNCg0KDQo=
--0016e68fa338b179c1048925a56e
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

2010\06\16@095841 by John Gardner

picon face
> Python is really very nice ...

Thanks. Think I'll look into Python a bit further.

Jack

2010\06\16@101106 by Olin Lathrop

face picon face
SME wrote:
> Attached is an example of extreme commenting.

I don't have a problem with the amount of comments, but it's a remarkable
example of how to write large volumes of largely useless babble.  The all
important what the module does is missing from the header comments.  It
dives right into details without any context.  I'm sure some of the context
would come from understanding what the overall system was supposed to do,
but still, there is nothing explaining what this module as a whole is
supposed to do and how it fits into the system.

You know bad code will follow when the module comments start with "Here add
a little bit of daring...".  Not only is this immature, but the word usage
is so messed up to make it difficult to follow.  Why is the programmer
telling us what we should be doing?  He probably meant to indicate that he
thinks this code is "daring", whatever that's supposed to mean to us.  The
missing periods, random capitalizations, and overall lack of neatness in
formatting make this module difficult to follow even if you had some idea
what it was supposed to do.

Some of the end of line comments are meaningful, but then there is stuff
like "K6L 20.8.97".  There's lots more, but I've got real code to write.

2010\06\16@101724 by Wouter van Ooijen

face picon face
> Thanks. Think I'll look into Python a bit further.

FYI: Python is my first choice for all PC programming. Nice syntax,
libraries for almost everything you can imagine, good portability to
Linux, etc.

Small minuses:
- slower that a language that compiles to machine code
- a user must either install python, or you'll have to wrap your program
using something like py2exe, the result will be big
- there is no compilation-time type checking
- there is no module abstraction other than using separate files

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\16@105737 by sergio masci

flavicon
face


On Tue, 15 Jun 2010, Wouter van Ooijen wrote:

{Quote hidden}

Yes I agree with you that sometimes "*why* something is done" is obscure.
And as you alude to yourself, this can be because someone else reading the
code you have written may not understand the complexities of the rules
involved. I understand this and agree, however, adding comments to the
code to clarify this is in my opinion probably not the best way to help
the reader. Where do you add the comments, everywhere the variable or
constant is used? Ok, maybe just where it is declared. So the programmer
ends up gathering together all variable and constant declarations and
commenting these. Fair enough. So now we have reduced the commenting of
our use of the variables and constants of our program. We have made it
easier for the reader to follow the code because he/she knows where to
find the information about these things. Consequently we don't need to
pepper our code with this redundent information. However now we have
another problem, we WANT to keep variables and constants belonging to
seperate modules with those modules and not be forced to move them to a
central place.

Your argument that "such a pointer belongs in the specifications" is a
good one. Perhaps what is needed is a seperate level of documentation that
sits between the specification and the source code, one that gives an
overview of variables, constants and algorithms - maybe arranged in a
hierachy. Then a reader could read that before diving into the code.

I think one of the biggest problems we have is that "people" expect to be
able to dive into some source code (at any point) and expect to be able to
quickly fix or change its behaviour without needing to understand the
entire system. And for this to happen they expect comments in the source
to help.

I argue that if you need to comment something like:

       // add the VAT to the subtotal giving the total.
       // VAT is a percentage

       t = s * (1 + v / 100);

Then the programmer is doing something seriously wrong.

Code commenting should be for obsure things that can't be calrified by
cleaning up the code. e.g.

       // note: reading the USART clears the receiver ready flag,
       // so save a copy of the receiver ready flag first
       flag = USART_status;
       ch   = USART_buff;

I also argue that you should use the computer and (development) software
to help you wherever possible. In short write your code so that it is
easier for the compiler to spot mistakes, easier for you to unit test
modules, easier for you to understand a module and simply replace it if
needed rather than waste time trying to track down obscure bugs in it.
Commenting does NOTHING to help the development software track down a
problem or identify a misunderstanding. Comments are open to user
interpretation. They can be broken by an update to the code. A relevent
comment might be in a place you haven't visited yet. Just because a
comment says something should never happen at this point in the code
doesn't make it so. If you need to put checks in place then put them in
place in which case the comment is redundent. If you don't need to put the
checks in then a comment wont help you anyway and it centainly wont help
the compiler of debugger.

Many people seem to think that it's ok for code to be obscure because it's
intended for a machine. Code doesn't have to be obscure, the intension of
the code doesn't have to be obscure. You can wrap it up so that it is easy
to follow and those bits which can't be should then be documented
(includeing comments if needed). But seriously, adding an ocean of
comments to your code doesn't help you write better code, it just lets you
get away with writing BAD code which on its own is hard to follow.


Regards
Sergio Masci

2010\06\16@111521 by Olin Lathrop

face picon face
sergio masci wrote:
> But seriously,
> adding an ocean of comments to your code doesn't help you write
> better code,

Yes it does.  Forcing yourself to explain what you're doing to that mythical
person looking over your shoulder catches mistakes that never become bugs.

One of the objections I have heard to comments is that they take time.  If
you use comments effectively, they actually save time just with the initial
writing and debugging of the code, let alone the savings in maintainence
later.

2010\06\16@113317 by Wouter van Ooijen

face picon face
>> But seriously,
>> adding an ocean of comments to your code doesn't help you write
>> better code,

An ocean might be a bit over the top, but writing some comments
certainly helps (compared to writing none). At the very least it forces
you to sit back and look at your code from a distance, and to ask
yourself "now what would a fresh reader of this code need to know to
understand it?".

Note that "help" is not the same as "force" or "guarantee" or the like.
There is still no silver bullet. (But Brooks has written a new book,
"The design of design".)

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\16@121904 by Marechiare

picon face
> FYI: Python is my first choice for all PC programming.
> Nice syntax, libraries for almost everything you can
> imagine, good portability to Linux, etc.
>
> Small minuses:
> - slower that a language that compiles to machine code
> - a user must either install python, or you'll have to wrap
> your program using something like py2exe, the result
> will be big
> - there is no compilation-time type checking
> - there is no module abstraction other than using
> separate files

Except for the second, those are huge minuses, in my opinion.

2010\06\16@122143 by sergio masci

flavicon
face


On Wed, 16 Jun 2010, Wouter van Ooijen wrote:

> >> But seriously,
> >> adding an ocean of comments to your code doesn't help you write
> >> better code,
>
> An ocean might be a bit over the top, but writing some comments
> certainly helps (compared to writing none).

I agree "some" will probably be necessary. What I really detest is when
people look at the code to comment ratio and dismiss the code (without
even bothering to try and understand it) because in their opinion there
are not enough comments. Forget that the code might actually be easy to
understand or that there may be explanitory documentation elsewhere that
clarifies everything.

> At the very least it forces
> you to sit back and look at your code from a distance, and to ask
> yourself "now what would a fresh reader of this code need to know to
> understand it?".

Yes I understand exactly what you are saying here. Sometimes I look at my
own code and think "this is too complex, I need to break it down more".
Sometimes I look at it and think "I need to do too much explaining, it's
crap, I need to re-write it". Sometimes, like you, I think "this needs
some reference to external stuff that explains why I'm doing this".

Like you, I don't try to explain *everything* in the comments embedded in
the code. That would just add noise and make it difficult to see what the
code is trying to do.

>
> Note that "help" is not the same as "force" or "guarantee" or the like.
> There is still no silver bullet.

Again I agree, but I think you've got to define the level of person you
are willing to help. I mean, are you going to write documentation that is
going to help a complete novice understand your code or an expert.
Probably someone on the same level as you if this is a comercial
application and probably someone at a lot lower level if it's for teaching
purposes.

Regards
Sergio Masci

2010\06\16@122752 by Ariel Rocholl

picon face
As you probably saw, there are plenty of opinions as the question is very
dependant on personal programming style, skillset, company you work on and
procedures you are asked to put in place (if any) and, of course, target
market for your application (bug acceptance is not the same for a safety
critical system than is for an advertising javascript webpage).

As this is personal in many aspects, you can safely ignore many of the
extreme comments from "comments are a must" to "comments are useless".
Comments and documentation in general may or may not be useful, depending on
many factors. Using previous sample Safety critical system implementation
will mandate you to strongly document every minor piece of your
design/code/test and map it to higher level requirements, being reviewed by
2 or more independent people, etc, and being maintained by many years. So
documentation of what you are expected to do is just mandatory, no question.
On the other hand, a web page may live for a day and be obsolete in just
hours, documentation may be overkill, useless and obvioulsy unnecesary cost
increase. Some developers don't have a vast experience on working in too
different systems so will offer a valid opinion but probably for the
applications they are familiar with.

For the specific context you ask the question for, sweet spot is probably in
the medium range of above two extreme examples. I would suggest the approach
of successive refinement and refactoring: start by a code that just works
for the main functionality you want, with minimal or no documentation at
all. Review your code to honestly criticize ugly parts (i.e. hard to
understand. inefficient, too large) and split in meaningful smaller
procedures and probably complement with comments. Depending on how much time
you want to dedicate to the task, refactoring over refactoring will put you
in a much cleaner code with limited documentation effort required.

Note above is about "refactoring for clarity and maintenability" which is
not necesarily the same than "refactoring for best performance".

HTH

2010/6/14 Marcel Birthelmer <RemoveMEmarcelb.listsTakeThisOuTspamspamgmail.com>

>
>
> So to get to the question - those of you that program significant
> amounts of code and complicated bits like TCP/IP stacks etc., what do
> you do to keep your code structured in a useful way?
>
>

--
Ariel Rocholl

2010\06\16@123702 by sergio masci

flavicon
face


On Wed, 16 Jun 2010, Olin Lathrop wrote:

> sergio masci wrote:
> > But seriously,
> > adding an ocean of comments to your code doesn't help you write
> > better code,
>
> Yes it does.  Forcing yourself to explain what you're doing to that mythical
> person looking over your shoulder catches mistakes that never become bugs.

The same could be said for designing the software properly before writing
the code. You could use flow charts, psuedo code, OO diagrams etc.

>
> One of the objections I have heard to comments is that they take time.  If
> you use comments effectively, they actually save time just with the initial
> writing and debugging of the code, let alone the savings in maintainence
> later.

Ok, granted you've found this to be true in your experience, however I
have found that:

(1) all to often too many comments obscure the real *warnings* that need
to be seen.

(2) tons of explantory comments are actually there because the code is
badly written and is difficult to follow. Here the answer is to re-write
the code, make it simpler so that you don't need to rely on the comments.

(3) the comments can be misleading and although they tell you that the
code is doing one thing, the code is actually doing something else because
the person that wrote it doesn't understand or someone has changed the
code and / or comments incorrectly.

In short I *always* find it more productive to work through the code and
treat the comments as suspect.

Regards
Sergio Masci

2010\06\16@124502 by Olin Lathrop

face picon face
sergio masci wrote:
> What I really detest is
> when people look at the code to comment ratio and dismiss the code
> (without even bothering to try and understand it) because in their
> opinion there are not enough comments.

Then you'll never work here.  This is one of the simple first pass filters I
use to look at a candidate's code.  I'm not expecting a comment on every
line for the quick visual style inspection, but a whole page of executable
code without a comment is a serious red flag.  After the first impression I
look more carefully, particularly at subroutine header comments, and then a
few random pieces of code in the middle of something.

The lack of comments in any one piece of code is not the issue, but the
sloppy nature that invariably accompanies sparse commenting is.  Those who
think there is such a thing as "self documenting" code need not apply.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@125109 by Olin Lathrop

face picon face
sergio masci wrote:
>> Yes it does.  Forcing yourself to explain what you're doing to that
>> mythical person looking over your shoulder catches mistakes that
>> never become bugs.
>
> The same could be said for designing the software properly before
> writing
> the code. You could use flow charts, psuedo code, OO diagrams etc.

Yes, and the two are independent.  I agree you don't want to just write code
without understanding the structure of the system it will fit into and how
it will fit within that structure.  None of that, however, should keep you
from writing good comments once you do start writing the actual code.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@125606 by Marechiare

picon face
>> But seriously, adding an ocean of comments to your
>> code doesn't help you write better code,
>
> Yes it does.  Forcing yourself to explain what you're
> doing to that mythical person looking over your shoulder
> catches mistakes that never become bugs.
>
> One of the objections I have heard to comments is that
> they take time.  If you use comments effectively, they
> actually save time just with the initial writing and
> debugging of the code, let alone the savings in maintainence
> later.

Depends on the person, I believe. Of course, "production" code is
expected to be that way (and it is expected to cost a lot, but what if
the budget is limited?).

But when developing and debugging the code some developers are quite
comfortable with keeping the uncommented code in their short-term (up
to week) mind "cache". The code is getting changed many times,
writing/rewriting comments at this stage would be just a waste of
time.

Of course, on cleaning the mind "cache" you need to give birth to
comments and write them down. In my better years (best years were
System 360 - related) I was able not only to handle the uncommented
code for weeks, I was able to write chunks of hundreds of PIC words
even without a compiler, just memorizing all the PIC's commands in
Hexadecimal. My programmer would then take the code from the text file
and burn it into a PIC.

But again, I agree 100% with Olin on comments for "production" code
(provided the budget were enough).

2010\06\16@134300 by sergio masci

flavicon
face


On Wed, 16 Jun 2010, Olin Lathrop wrote:

> sergio masci wrote:
> > What I really detest is
> > when people look at the code to comment ratio and dismiss the code
> > (without even bothering to try and understand it) because in their
> > opinion there are not enough comments.
>
> Then you'll never work here.

Don't sweat it Olin, you couldn't afford me anyway :-)

>  This is one of the simple first pass filters I
> use to look at a candidate's code.  I'm not expecting a comment on every
> line for the quick visual style inspection, but a whole page of executable
> code without a comment is a serious red flag.  After the first impression I
> look more carefully, particularly at subroutine header comments, and then a
> few random pieces of code in the middle of something.

So do you actually work through the code and check it against the
comments, or do you just skim the code and belive the comments? It's far
more important to me that I be able to work through someone's code without
having to perform contortions - that I don't have to rely on comments that
cannot be automatically verified.

>
> The lack of comments in any one piece of code is not the issue, but the
> sloppy nature that invariably accompanies sparse commenting is.

Why "invariably"? You seem to have had exposure to a lot of crap source
code that you found hard to follow or you've worked with a lot of very
poor programmers who couldn't cut it.

>  Those who
> think there is such a thing as "self documenting" code need not apply.

As I said before, I'm not an advocate of "self documenting code", but I do
belive you can write code so that it is simple to follow and requires a
low level of commenting.

which part of the above following line is true?

       rrf        fred                ; increment fred


Regards
Sergio Masci

2010\06\16@135029 by RussellMc

face picon face
> Depends on the person, I believe. Of course, "production" code is
> expected to be that way (and it is expected to cost a lot, but what if
> the budget is limited?).

If the budget is limited and you want to achieve minimum cost, then
you should, of course, take care to comment very well indeed.



             Russell

2010\06\16@135638 by Harold Hallikainen

face
flavicon
face

>> One of the objections I have heard to comments is that
>> they take time.  If you use comments effectively, they
>> actually save time just with the initial writing and
>> debugging of the code, let alone the savings in maintainence
>> later.
>

Does generating comments really take time? I can type about as fast as I
can think, so it really takes no time to comment as I go along. I'm
thinking how the code works anyway, so it's real quick to write it down.

Harold


--
FCC Rules Updated Daily at http://www.hallikainen.com - Advertising
opportunities available!

2010\06\16@143050 by Marechiare

picon face
> If the budget is limited and you want to achieve
> minimum cost, then you should, of course, take
> care to comment very well indeed.

Or not to comment at all in the case :-)

2010\06\16@143614 by Jim

flavicon
face
Actually if you RRF Fred, you'll multiply by 2, not just increment.
Unless you start out with 1 or 2 to begin with.

Jim

---{Original Message removed}

2010\06\16@143635 by Olin Lathrop

face picon face
sergio masci wrote:
> So do you actually work through the code and check it against the
> comments, or do you just skim the code and belive the comments? It's
> far more important to me that I be able to work through someone's
> code without having to perform contortions - that I don't have to
> rely on comments that cannot be automatically verified.

During a interview I'm only trying to get a impression of the person and how
good a engineer the candidate is.  Good engineering requires attention to
detail.  This appears to be a overall character trait.  When someone is
sloppy about one thing, they are invariably sloppy in other areas too.  I
have never seen a sloppy person make a good engineer.

Stepping back and thinking about each line of code you write at one level
higher, then writing down that explanation, and for sections of code, and
following some basic style rules shows attention to detail.  The opposite is
the "eh, who cares" or "eh, I'll get to it later" attitude that is a sure
sign of a poor engineer.  So comments and consistant style are things to
measure a software engineer by directly, but more importantly for a
interview, they are a good indicator of the mentality required for
engineering.

Also keep in mind that any code that a candidate shows you during a
interview was carefully picked.  If that code is even marginally sloppy,
imagine what the rest looks like.

>> The lack of comments in any one piece of code is not the issue, but
>> the sloppy nature that invariably accompanies sparse commenting is.
>
> Why "invariably"?

It's just how people are.  We may think we can change our style, but we
really can't much and for long.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@144347 by Olin Lathrop

face picon face
jim@jpes.com wrote:
> Actually if you RRF Fred, you'll multiply by 2, not just increment.

No, you'll roughly divide by 2, although the high bit of the result is
uncertain in this snippet because we can't see how the C bit was previously
set.  For example, this would do a integer divide by 2 of a unsigned number:

    bcf   status, c  ;set 0 bit to shift in
    rrf   fred       ;divide by 2

Whereas this does a integer divide by 2 of a signed number:

    rlf   fred, w    ;replicate sign bit to shift in
    rrf   fred       ;divide by 2


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@151557 by Herbert Graf

picon face
On Wed, 2010-06-16 at 14:36 -0400, Olin Lathrop wrote:
> Stepping back and thinking about each line of code you write at one level
> higher, then writing down that explanation, and for sections of code, and
> following some basic style rules shows attention to detail.  The opposite is
> the "eh, who cares" or "eh, I'll get to it later" attitude that is a sure
> sign of a poor engineer.  

Not always true.

Engineers work with compromises. A good engineer will choose the best
compromises. Unfortunately (or fortunately depending on your
perspective) that decision does not always lie with the engineer.

I've seen many cases where the engineer simply was not given the TIME to
do proper documentation (this includes commenting, but extends to many
other areas). I think everybody here knows that sometimes you are in a
time crunch, and the "details" start to go by the wayside.

Yes, in the long run everything takes more time without proper
documentation, but to label the engineer as "bad" is incorrect.

Yes, sample code brought to an interview cannot invoke this excuse.

TTYL

2010\06\16@153110 by Marechiare

picon face
{Quote hidden}

Yes, exactly what I tried to say. I talked about budget limitation.
That's the same as time limitation, in the context.

2010\06\16@154436 by Olin Lathrop

face picon face
Herbert Graf wrote:
> I've seen many cases where the engineer simply was not given the TIME
> to
> do proper documentation (this includes commenting, but extends to many
> other areas).

Some documentation does take time, but commenting code as you write it takes
so little extra and *saves* time even the first time thru.  Not commenting
code because of a deadline is simply a fallacy.

Think about it.  How many milliseconds does it take per line to add a
comment?  And then is your line writing really limited by typing anyway?
Actually chunks of lines often are, but the additional wait time to think
about a chunk before writing it dwarfs the extra little time the comments
will take to write in that chunk.  Weigh that against the minutes or even
hours to find and fix a single bug that could have been avoided by forcing
yourself to explain your code to the mythical person looking over your
shoulder.  It just doesn't add up.  Code comments *save* time, and not just
in the long run.  If nothing else, think of them as a low cost first pass
debugging step.

> I think everybody here knows that sometimes you are in a
> time crunch, and the "details" start to go by the wayside.

Only for bad engineers.  Some additional investigation and the like may go
by the wayside, but the implementation details can't.

> Yes, sample code brought to an interview cannot invoke this excuse.

Exactly.  Although you'd probably be surprised at some of the excuses I've
heard about code brought to a interview.  I haven't heard one I consider
valid yet.  This is like interviewing for loan officer of a bank and showing
up in a T shirt and jeans.  The excuse "my good clothes are in the laundry"
is just going to make you look more stupid than you already do.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@161858 by Herbert Graf

picon face
On Wed, 2010-06-16 at 15:44 -0400, Olin Lathrop wrote:
> Herbert Graf wrote:
> > I've seen many cases where the engineer simply was not given the TIME
> > to
> > do proper documentation (this includes commenting, but extends to many
> > other areas).
>
> Some documentation does take time, but commenting code as you write it takes
> so little extra and *saves* time even the first time thru.  

True.

> Not commenting
> code because of a deadline is simply a fallacy.

Not true. Why? Because I don't think anybody on the planet can write a
program that is "correct" the first time through.

Software has bugs. Fixing those bugs often requires many iterations of
changing of the code, sometimes little things (i.e. where a loop
terminates), sometimes big things (changing a routine to run
recursively).

As a result, comments get "out of date". If you're changing a routine
multiple times in order to narrow down a problem it is NOT reasonable to
expect the comment to be updated in every iteration if you are under a
time crunch.

When the issue is resolved undoubtedly another issue appears, and more
comments get out of sync.

A "good" engineer with enough time in the budget will then go over the
changes and ensure comments are corrected/amended/removed as necessary.
This is non trivial time wise, and sometimes not worth the effort
(update the comments or miss the deadline and get fired? Hmmm...).

> > I think everybody here knows that sometimes you are in a
> > time crunch, and the "details" start to go by the wayside.
>
> Only for bad engineers.  Some additional investigation and the like may go
> by the wayside, but the implementation details can't.

Sorry Olin, I live in the real world, I know that is not universally
true. When a deadline looms details DO go by the wayside, a good
engineer doesn't just focus on details, he/she focuses on what's
necessary to solve the problem, sometimes a kludge is acceptable if it
means the product meets the deadline.

> > Yes, sample code brought to an interview cannot invoke this excuse.
>
> Exactly.  Although you'd probably be surprised at some of the excuses I've
> heard about code brought to a interview.  

To be frank, I consider sample code in an interview useless, since it
doesn't tell me much more then the resume. Sample code is easy to
perfect (since the candidate has a near infinite amount of time to get
it that way), might not even BE from the candidate (a friend wrote it
and told them what it did) and shows nothing as to the candidates ACTUAL
attention to detail and skill while working under a crunch.

When we interview we actually ask technical questions and have the
candidate write code in front of us on the white board. That is where
you start to get an idea of their proficiency. It becomes clear very
quickly whether the person is a good fit.

TTYL

2010\06\16@181632 by Olin Lathrop

face picon face
Herbert Graf wrote:
> Not true. Why? Because I don't think anybody on the planet can write a
> program that is "correct" the first time through.
>
> Software has bugs. Fixing those bugs often requires many iterations of
> changing of the code, sometimes little things (i.e. where a loop
> terminates), sometimes big things (changing a routine to run
> recursively).

But this is exactly where comments help.

> As a result, comments get "out of date". If you're changing a routine
> multiple times in order to narrow down a problem it is NOT reasonable
> to expect the comment to be updated in every iteration if you are
> under a time crunch.

Of course it is, since doing so **saves time**.  As you write new code, you
write the comments to go with it.  The same logic for writing comments in
the original code applies to any changes.

You also make it sound like debugging changes a lot of code.  Usually very
little code actually changes as a result of debugging.  You mostly find
stupid stuff where you forgot to add or subtract 1, added where you meant to
multiply, etc.  It's actually quite rare that major structural changes are
required as a result of debugging.  The vast majority of code does "just
work".

Today is as good a example as any.  I was adding offset and gain calibration
capability to firmware I'm in the middle of developing for a 30F4013.  The
actual offset and gain computation is rather trivial.  The larger amount of
code had to do with commands and responses to get the values from the host,
write them to EEPROM, send various values to the host so it can compute
calibration values, the host test program code to provide a user interface
to the new commands and response, compute calibration values from raw
numbers in a file, update the docs for the new commands, etc.

In this process I made two mistakes.  In one place I was accumulating 16 bit
A/D readings into a 32 bit value, and forgot to sign extend.  It's not that
I didn't know I needed to, but when it came to writing the code I just
forgot.  The second mistake was not clipping the result of the calibration
computation to the full scale range.  Previously this variable held the raw
A/D reading which couldn't exceed 32767.  After offset and gain was applied
it could, and I forgot that this variable was treated as a signed number in
some cases, so the out of range values wrapped to negative.

In both cases, the problem was evident from the symptoms, and the fixes were
trivial, just a couple lines of code in either case.  I didn't even use the
debugger, just dumped new versions to the board and looked at the symptoms.

Of course I've made bigger mistakes that took a lot longer to figure out,
but what happened today is more typical.  Think about it.  How long do you
really spend debugging and how much does the fix end up changing the code?

> A "good" engineer with enough time in the budget will then go over the
> changes and ensure comments are corrected/amended/removed as
> necessary.

In my experience, that never gets done.  Once it's a mess, everybody always
has something better to do than to clean up the mess.

> This is non trivial time wise, and sometimes not worth the effort
> (update the comments or miss the deadline and get fired? Hmmm...).

Non-trivial only if you let it get that way in the first place.  Letting
that happen is bad software development and counter-productive, especially
when a deadline is looming.

{Quote hidden}

I actually agree with this.  Sample code is only to show the "guaranteed not
to exceed" level.  It's amazing how low that level often is though, which is
why it's still useful to look at.  Perfect sample code is no proof of
anything, but bad sample code is.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\16@203023 by ivp

face picon face
> I've seen many cases where the engineer simply was not given the
> TIME to do proper documentation (this includes commenting, but
> extends to many other areas). I think everybody here knows that
> sometimes you are in a time crunch, and the "details" start to go by
> the wayside.

Time before the due date can be short, but I always make some
effort to tidy up afterwards, if only for my own records and personal
satisfaction. This helpful when and if a review is necessary

2010\06\16@235416 by Vitaliy

face
flavicon
face
ivp wrote:
>> I've seen many cases where the engineer simply was not given the
>> TIME to do proper documentation (this includes commenting, but
>> extends to many other areas). I think everybody here knows that
>> sometimes you are in a time crunch, and the "details" start to go by
>> the wayside.
>
> Time before the due date can be short, but I always make some
> effort to tidy up afterwards, if only for my own records and personal
> satisfaction. This helpful when and if a review is necessary

Agile/refactoring/self-documenting code help a lot with this. You don't have
a "cleanup phase", it is seamlessly integrated into the process.

Vitaliy


2010\06\17@002918 by RussellMc

face picon face
> Agile/refactoring/self-documenting code help a lot with this. You don't have
a "cleanup phase", it is seamlessly integrated into the process.


A few exemplary paragraphs would be good.


  R

2010\06\17@013152 by Marechiare

picon face
>> > I think everybody here knows that sometimes you
>> > are in a time crunch, and the "details" start to go by
>> > the wayside.
>>
>> Only for bad engineers.  Some additional investigation
>> and the like may go by the wayside, but the
>> implementation details can't.
>
> Sorry Olin, I live in the real world, I know that is not
> universally true. When a deadline looms details DO go
> by the wayside, a good engineer doesn't just focus on
> details, he/she focuses on what's necessary to solve
> the problem, sometimes a kludge is acceptable if it
> means the product meets the deadline.

Defending "a kludge" practice is not a good idea as for me. And I did
not mean it when I said that sometimes for some developers it's OK to
go with almost no comments. Clean, well-structured, self-explanatory
code by the only developer on a project could be OK within some
reasonable time span when working on a separate program module, in my
opinion.

2010\06\17@020657 by ivp

face picon face
>> the problem, sometimes a kludge is acceptable if it
>> means the product meets the deadline.

> Defending "a kludge" practice is not a good idea as for me

Well, there are kludges and then there are kludges. Some may put
the product out of spec, and even a little O/S might disappoint some
customers. No comments won't affect a product's performance, but
could have other consequences that may affect that one and/or future
products or the business


2010\06\17@133316 by Dwayne Reid

flavicon
face
At 12:06 AM 6/17/2010, ivp wrote:

>No comments won't affect a product's performance, but could have
>other consequences that may affect that one and/or future
>products or the business

I've been following this thread with great interest.

I don't consider myself to be a 'great' programmer - I'm competent
with PIC assembler but definitely NOT a superstar.

For example, Vitaliy talks of 'self-documenting' code.  Because I am
not used to reading such code, I think that it would take me days to
learn from the code what the system is supposed to be doing.

For me, what works is comments.  Lots and lots of comments.

Comment blocks at the top of each major code block that tells me what
the intent of that block is.  The comments tell me any 'gotchas' that
might bite me if I make changes a couple of years down the road.

Comments at the end of many line of code that say useful things like
"active LO" or "active HI" or "cntr decs to 1, then
stops".  Sometimes the line comments say obvious things - but not often.

For example, look at the following code chunk.

;mulitply MS digit by 10, add LS digit, done!
    movwf       TMP0            ;W contains MS TW value
    addwf       TMP0,F          ;*2, clr C
    rlf         TMP0,F          ;*4
    addwf       TMP0,F          ;*5, clr C
    rlf         TMP0,W          ;*10
    addwf       TW_LSB,W        ;add ones digit
    movwf       TW_TIME         ;thumbwheel time delay in 100ms ticks
    goto        DoneTW

The comments at the end of each line tell me years later ** WHY ** I
used 'addwf' instead of 'rlf' when I wanted to double the value
contained in TMP0 in line 2.  Yeah - what the code is doing is
obvious, especially when you read the comments.  But would you notice
that its important that C be cleared if modifying that code several
years down the road?  Would you notice that you would have to
pre-clear C if you did decide to change that 'addwf' to 'rlf'?

I guess the best way I can put it is this: comments are for MY
benefit.  Not the customer's.  They help ME do a better job.

Olin says that writing comments adds hardly any time to writing the
code.  I'm not Olin, I'm not even in the same league.  I find that
writing useful comments - especially the comments at the front of
major code blocks - takes time.

But the time spent writing those comments IS useful.

Its useful while writing the comments - they help clarify in my mind
what the code should be doing.  Its useful when writing the code - I
can look at the comment block to make sure that I'm doing what I'm
supposed to be doing.

On the other hand - writing comments at the end of lines of code
takes almost no extra time.  The key here is to be careful NOT to
write useless or trivial comments - its shockingly easy to write
useless stuff because your head is wrapped up in what the code is
doing.  You have to exercise discipline to NOT write obvious comments.

dwayne

--
Dwayne Reid   <EraseMEdwaynerspamspamspamBeGoneplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\17@134605 by Vitaliy

face
flavicon
face
RussellMc still doesn't bother to switch his email client to not use
quoted-printable, but I forgive him:
>> Agile/refactoring/self-documenting code help a lot with this. You don't
>> have
a "cleanup phase", it is seamlessly integrated into the process.
>
> A few exemplary paragraphs would be good.


I've described the agile methodology, refactoring, and the concept of
self-documenting code on many occasions. Which part do you want me to
explain? :)

Vitaliy



2010\06\17@141404 by Vitaliy

face
flavicon
face
Dwayne Reid wrote:
> For example, Vitaliy talks of 'self-documenting' code.  Because I am
> not used to reading such code, I think that it would take me days to
> learn from the code what the system is supposed to be doing.

I think you would be surprised at how much easier it is to read
self-documenting code, than to follow the comments.

Here is a snippet of code from an actual project (an ECU simulator):

   int main(void)
   {
     Initializer_InitializeAll();
     StnEcuSim_Run();

     return 0;
   }

Few will disagree that comments would be completely redundant here. Or, for
example, if you see this function call:

   StnUart_SetBaudRate(UART_1, 9600);

Do you need a comment to tell you that it sets the baud rate of UART1 to
9600?

Comments have a number of huge drawbacks. First, they double the amount of
work upfront: you say what you want to say in code, then you explain what
the code says. It gets worse: code changes, so now you have to update the
corresponding comments. And you have to update them in multiple places, and
you are never sure that you got them all. You can't completely trust the
comments, so you have to read the code too, to verify.

In practice, comments are either omitted because they create too much extra
work (and you're in a hurry) or they act as a straightjacket: you want to
restructure a block of code, but you know that you will have to change all
the line comments too, so you say "forget it."

Self-documenting code does not have these problems. You just follow a few
simple rules, for example a function name should describe exactly what a
function does. If there is a discrepancy, it usually means that the name is
wrong, or the function is doing too much and needs to be split up. When you
change the name of the function, the compiler won't let you forget to change
it everywhere.

Vitaliy

2010\06\17@143213 by Wouter van Ooijen

face picon face
>     int main(void)
>     {
>       Initializer_InitializeAll();
>       StnEcuSim_Run();
>
>       return 0;
>     }
>
> Few will disagree that comments would be completely redundant here. Or, for
> example, if you see this function call:

I don't have a clue what an StnEcuSim and why it should be run.

>     StnUart_SetBaudRate(UART_1, 9600);
>
> Do you need a comment to tell you that it sets the baud rate of UART1 to
> 9600?

No, but I would appreciate a hint
- why it should be set at 9k6
- why UART_1 must be used
- why a UART must be used at all

> you say what you want to say in code, then you explain what
> the code says.

No, of course not, why should you do that if the code already states
that clearly? It is the things that the code does not tell that must
somehow be documented.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\17@150833 by Olin Lathrop

face picon face
Vitaliy wrote:
>     int main(void)
>     {
>       Initializer_InitializeAll();
>       StnEcuSim_Run();
>
>       return 0;
>     }
>
> Few will disagree that comments would be completely redundant here.

Don't speak for everyone.

Comments could serve useful purposes here.  Since this appears to be the
root routine of this project, there should be some explanation of what it
does.  Also, does STNECUSIM... ever return?  Could I safely delete RETURN 0?
If so, why is it there?  If not, where does it go, if this is a embedded
project without a operating system?  If this is on a machine with a OS and
it does return, why can the exit status only be 0?  Is there no possibility
of runtime errors?  Why not?

If this is all MAIN does, then it's not a terribly useful routine, largely a
waste of one subroutine call level.

> Comments have a number of huge drawbacks. First, they double the
> amount of work upfront: you say what you want to say in code, then
> you explain what the code says.

No, you explain the next level up of *why* the code is doing what it's
doing.  You assume others can read the language.  But that only tells you
what, not why, or how it fits into the bigger picture.  Occasionally when
you do something obscure, it's also good to explain what the code is doing
if there is a reasonable chance of confusion even amongst people that know
the language well.

> Self-documenting code does not have these problems.

Neither do purple flying pigs, since those don't exist either.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\17@151655 by Dwayne Reid

flavicon
face
At 12:32 PM 6/17/2010, Wouter van Ooijen wrote:

>It is the things that the code does not tell that must somehow be documented.

Thank you!  You've just managed to put into one sentence how I feel
about documentation.

dwayne

--
Dwayne Reid   <RemoveMEdwaynerKILLspamspamplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\17@161011 by Vitaliy

face
flavicon
face
Wouter van Ooijen wrote:
>>     int main(void)
>>     {
>>       Initializer_InitializeAll();
>>       StnEcuSim_Run();
>>
>>       return 0;
>>     }
>>
>> Few will disagree that comments would be completely redundant here. Or,
>> for
>> example, if you see this function call:
>
> I don't have a clue what an StnEcuSim and why it should be run.

ECUsim is a device that simulates ECUs (Electronic Control Units), but I
assure you that if you were a programmer working on this project, you would
not need the comments to tell you this.


>>     StnUart_SetBaudRate(UART_1, 9600);
>>
>> Do you need a comment to tell you that it sets the baud rate of UART1 to
>> 9600?
>
> No, but I would appreciate a hint
> - why it should be set at 9k6
> - why UART_1 must be used
> - why a UART must be used at all

If you really need to know all these things, by all means -- write a comment
block. We found that in the places where it's used, it raises none of the
questions (even from newcomers).

The last one especially seems contrived. "Yeah, why not Ethernet, IR, or
fiberoptic?"


>> you say what you want to say in code, then you explain what
>> the code says.
>
> No, of course not, why should you do that if the code already states
> that clearly? It is the things that the code does not tell that must
> somehow be documented.

I agree with that statement. However, look at the code that is out there.
Most of it is there to explain the things that you could write in code.

Vitaliy

2010\06\17@161125 by Vitaliy

face
flavicon
face
Olin Lathrop wrote:
> Neither do purple flying pigs, since those don't exist either.

While we're on the subject -- I think I'm done casting pearls. :)

On some level, it is funny to watch the attempts by the naysayers to explain
why a method that worked spectacularly well for several of our major
products, cannot work. But mostly, it's disappointing to see that so many
are willing to criticize what they don't understand, and so few that are
willing to listen with an open mind.

Vitaliy

2010\06\17@173243 by Bob Blick

face
flavicon
face
On Thu, 17 Jun 2010 13:09:23 -0700, "Vitaliy" said:

> write a comment block.

So after all this, it turns out you use "comment blocks" instead of
"comments".

Nice distinction.

Cheers,

Bob

--
http://www.fastmail.fm - Or how I learned to stop worrying and
                         love email again

2010\06\17@174344 by Dwayne Reid

flavicon
face
At 02:10 PM 6/17/2010, Vitaliy wrote:

>On some level, it is funny to watch the attempts by the naysayers to explain
>why a method that worked spectacularly well for several of our major
>products, cannot work. But mostly, it's disappointing to see that so many
>are willing to criticize what they don't understand, and so few that are
>willing to listen with an open mind.

On the contrary, Vitaliy.

I am ** extremely ** interested in this discussion.  But I would need
to see some concrete examples of WHY what you are proposing is so
wonderful.  As it stands, all we have is you saying that it works well.

While I can understand that what you are talking about works so well
for you, you don't give any guidance how the rest of us can learn
this technique.

You mentioned that it took you many years to learn to write programs
using this technique.  How can we be expected to agree with you when
we don't have that experience, and no way of seeing examples of this technique.

I've mentioned previously that I consider myself to be a mid-level
assembler programmer.  I'm not a newbie and I've undertaken some
pretty complex projects - and completed them successfully.  But I
take far longer to write complex software than I would like and am
extremely interested in improving my skill.  I suspect that many of
us on the PIClist feel the same way.

By all means - feel free to expound on your techniques.  But you
better be prepared to SHOW us why its so much better, else you are
going to keep getting the response that you are currently getting.

Like I mentioned previously - copious comments are the only thing
that saves me when I have to dig into a project that I haven't
touched in 10 or 15 years.  And - yes: some of our customers are
running equipment that is that old (or older) and don't think that it
is unreasonable to ask if they can have some changes made to
accommodate some new wrinkle in their production of their
products.  We try to accommodate those requests if possible (it can
be quite lucrative <grin>).

dwayne

--
Dwayne Reid   <dwaynerSTOPspamspamspam_OUTplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\17@174938 by Vitaliy

face
flavicon
face
Bob Blick wrote:
>> write a comment block.
>
> So after all this, it turns out you use "comment blocks" instead of
> "comments".
>
> Nice distinction.

OK, we're now down to wordpicking. :)

Write a comment block, a block of comments, a line comment, a reference to a
file with comments...

I don't understand what is so difficult to understand. I'm not against
comments per se. I use comments when necessary (to put a number on it, let's
say I end up with an average of one comment per 100 lines of C code). The
problem is, the code that's out there (Microchip is a popular target) is
plastered with comments to hide the ugly code underneath.

Vitaliy

2010\06\17@175401 by Dwayne Reid

flavicon
face
At 12:13 PM 6/17/2010, Vitaliy wrote:

>Self-documenting code does not have these problems. You just follow a few
>simple rules

I'm curious, though.

Take the snippet of code that I posted earlier.  I'll post it again -
its short.

;mulitply MS digit by 10, add LS digit, done!
    movwf       TMP0            ;W contains MS TW value
    addwf       TMP0,F          ;*2, clr C
    rlf         TMP0,F          ;*4
    addwf       TMP0,F          ;*5, clr C
    rlf         TMP0,W          ;*10
    addwf       TW_LSB,W        ;add ones digit
    movwf       TW_TIME         ;thumbwheel time delay in 100ms ticks
    goto        DoneTW

Which of the above comments would you delete?  Why?

For me, deleting those comments would be insanity.  There is NO way
that I could count on remembering WHY the code was written the way it
is after many years have gone by.

How would YOU like to make changes to that code snippet without the
comments to help you?

dwayne


--
Dwayne Reid   <spamBeGonedwaynerSTOPspamspamEraseMEplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\17@180402 by Vitaliy

face
flavicon
face
Dwayne Reid wrote:
>>On some level, it is funny to watch the attempts by the naysayers to
>>explain
>>why a method that worked spectacularly well for several of our major
>>products, cannot work. But mostly, it's disappointing to see that so many
>>are willing to criticize what they don't understand, and so few that are
>>willing to listen with an open mind.
>
> On the contrary, Vitaliy.
>
> I am ** extremely ** interested in this discussion.  But I would need
> to see some concrete examples of WHY what you are proposing is so
> wonderful.  As it stands, all we have is you saying that it works well.

I would love to post some of our code, but the code is proprietary and if I
don't post enough there is not enough context and Olin, Wouter et al will
rip it to shreds. I am not one to hide in the corner when I'm publicly
ridiculed, but my time is valuable and I don't like to waste it.


> While I can understand that what you are talking about works so well
> for you, you don't give any guidance how the rest of us can learn
> this technique.

Have you read the thread I referenced earlier? We've been through this
before, and instead of repeating myself I would rather answer clarifying
questions.


> You mentioned that it took you many years to learn to write programs
> using this technique.

You must have misunderstood. It didn't take me many years to learn the
technique, it took me many years to discover it. Learning it is easy.


> How can we be expected to agree with you when
> we don't have that experience, and no way of seeing examples of this
> technique.

Most people seem to be content using what they've got, and they are
reluctant to change. I remember that I was very motivated to find a better
way to program, when I got frustrated with the way I was used to
programming. I'm sorry, I am a small business owner with a wife and three
young kids, so I don't have the time to serve it on a silver platter. Read
the thread, ask questions, and try it for yourself. I don't know an easier
way.


{Quote hidden}

See above. :) I am not at all surprised by the response, because I've been
there before. The old-timers think that agile is some kind of voodoo, even
though it's over a decade old and had become mainstream.


> Like I mentioned previously - copious comments are the only thing
> that saves me when I have to dig into a project that I haven't
> touched in 10 or 15 years.  And - yes: some of our customers are
> running equipment that is that old (or older) and don't think that it
> is unreasonable to ask if they can have some changes made to
> accommodate some new wrinkle in their production of their
> products.  We try to accommodate those requests if possible (it can
> be quite lucrative <grin>).

Your situation is different, as I said many times -- I don't program in
assembly. I'm not working on projects that sell in the millions of units, so
I use C to maximize the ROI. The use of assembler is justified if you're
programming for the 10F, optimizing a small portion of C code, or you're
just so much better programming in assembly that the time it would take to
master a higher level language is not worth the benefit.

Vitaliy

2010\06\17@180517 by Vitaliy

face
flavicon
face
Dwayne Reid wrote:
{Quote hidden}

I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.
I DON'T PROGRAM IN ASSEMBLY.

Are we clear? :)

Give me a reasonably small/straightforward project written in C, and I'd be
happy to show you. :)

Vitaliy

2010\06\17@183814 by Olin Lathrop

face picon face
Vitaliy wrote:
> I would love to post some of our code, but the code is proprietary

That's a really weak argument.  Surely you have a reasonably sized module
somewhere that does not show any intellectual property of your products.
I'm not trying to get the secrets of how you process OBDII messages accross
different vehicles, but I suspect only a small fraction of your code deals
with that.

> and if I don't post enough there is not enough context and Olin,
> Wouter et al will rip it to shreds.

Don't worry, we'll do that anyway ;-)


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\17@190656 by Dario Greggio

face picon face
Vitaliy ha scritto:

> On some level, it is funny to watch the attempts by the naysayers to explain
> why a method that worked spectacularly well for several of our major
> products, cannot work. But mostly, it's disappointing to see that so many
> are willing to criticize what they don't understand, and so few that are
> willing to listen with an open mind.


for the records, Vitaliy, I agree with you on this matter.
Not to say that I dislike other people's work, I mean :) anyway

--

Ciao, Dario
--
Cyberdyne

2010\06\17@195622 by Neil Cherry

flavicon
face
Note, I'm not an expert at programming but I have a degree (for
what it's worth) and I've been programming since 1977. I went as
far as to learn how to reverse engineer code (via Don Lancaster's
methods if anyone is old enough to remember). I don't code as a
profession, I'm a network engineer but I write code to run tests
and generate complex traffic. I also code for my own needs.

When I reverse engineer code I comment like mad so I can make
sense of what's there. Once it's done I clean that up. For code
(assembly, compiled, scripts, etc.) I comment my notes (which are
stated as notes, my references and I use block comments to explain
complex things. I like to break my code into functions with
descriptive names so I don't need to search for the function later
to find out what it does/did. I also keep an engineer's notebook
for projects so I can keep drawing and further notes. I'll reference
that when the subject is too complex to be added to the code.
Usually when I get to that level I rewrite the code to simplify it.
I do all this so the next guy who comes along can figure out what
was done. It's usually me and that part works. It doesn't always
work, especially when I change something and the documentation is
no long in sync but I've even gotten into the habit of noting that
before I clean up the code/comments completely. I use all the methods
of commenting and self documenting code except for the ridiculously
long name methods that includes tell what it returns. This works
well for me and a few other (non-professional) programmers have
commented that they generally like my code (my algorithms are
another story ;-). I've done all this mostly for myself because
I'm still maintaining code from 1985 (and much more modern code
too). The only thing I know is not to state the obvious (c = a + b)
but rather comment on what a, b, and C are (self documenting code
would be useful here).

--
Linux Home Automation         Neil Cherry       KILLspamncherryspamBeGonespamlinuxha.com
http://www.linuxha.com/                         Main site
http://linuxha.blogspot.com/                    My HA Blog
Author of:            Linux Smart Homes For Dummies

2010\06\17@205328 by Vitaliy

face
flavicon
face
Olin Lathrop wrote:
>> I would love to post some of our code, but the code is proprietary
>
> That's a really weak argument.  Surely you have a reasonably sized module
> somewhere that does not show any intellectual property of your products.
> I'm not trying to get the secrets of how you process OBDII messages
> accross
> different vehicles, but I suspect only a small fraction of your code deals
> with that.

A large portion, actually, but that's not even the point. We're suing a guy
who stole our code/designs back in 2005 (we discovered the fact only
recently), and I am paranoid about releasing anything that he can turn
around and use to his advantage.

If Dwayne is really interested in improving the way he structures his code
(and it sounds like he is), he will figure it out. It's not my goal to
convince anyone against their will or prove them wrong.


>> and if I don't post enough there is not enough context and Olin,
>> Wouter et al will rip it to shreds.
>
> Don't worry, we'll do that anyway ;-)

I would be disappointed if you didn't.  ;-)

Vitaliy

2010\06\17@215224 by jim

flavicon
face
My 2 cents worth.  I don't condone writing sloppy code.  But, if someone has
written sloppy code,
and if I have to use it or maintain it, or whatever, I'd be grateful that
someone put a boat load
of comments in there.  Providing they actually say something, and are not
just there for the sake
of just being there.

If the code does what it is supposed to do, and there are comments that tell
me important information
About that code, then I can live with the sloppiness.

Jim

{Original Message removed}

2010\06\17@225148 by Mike snyder

picon face
On Thu, Jun 17, 2010 at 6:38 PM, Olin Lathrop <EraseMEolin_piclistspamEraseMEembedinc.com> wrote:
> I'm not trying to get the secrets of how you process OBDII messages accross
> different vehicles, but I suspect only a small fraction of your code deals
> with that.

Heh, no rocket science this OBDII used by all automotive companies so
enought people know about it. OBD II is a standard heck there is even
enough open source software out there to roll your own quickly and
easily, as always google knows

http://picobdii.googlecode.com/svn/trunk/Code/

Mike

2010\06\18@012858 by Wouter van Ooijen

face picon face
>> No, of course not, why should you do that if the code already states
>> that clearly? It is the things that the code does not tell that must
>> somehow be documented.
>
> I agree with that statement. However, look at the code that is out there.
> Most of it is there to explain the things that you could write in code.

Indeed I often see comments that should not be there. But I also see
comments (or I don't see them where they should be) that explain what I
want to know, so I can't agree with something like "self-documenting
code makes all comments redundant". The point is of course the "all"
word. I can agree with weaker statements, like "a lot of comments out
there are worse than no comment", or "a lot of comments out there should
be replaced by better variable names". But note the "a lot", not "all".

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\18@042308 by Michael Watterson

face picon face
Vitaliy wrote:
{Quote hidden}

I have no ambition to make changes to other people's Assembler. Often I
will figure out the overall logic and test it as a skeleton in C or VB6
before re-implementing in High level Language.
{Quote hidden}

In fact if you have a COMPLEX, LARGE project to do and there is no high
level language and you *REALLY* have to use the chip (It does something
wonderful that a PIC18 or ARM Cortex or x86 can't do).

You 1st write or pay someone else to write a compiler. Or at worst use  
Macro Assembler to implement a Forth like Language.

Too many comments and they get out of sync with code. Only HLL code can
be "self documenting" IMO. That's why I do an absolute minimum of
Assembler.  On  any  non-trivial  size of  project any  savings  of  
space and  speed using assembler can be an illusion.

I use comments (Block, inline and end of line as appropriate) sparingly,
and mostly just to explain what isn't evident from code. This is also
why I dislike intensely Reverse Hungarian and it's cousins. I also
prefer a Compiler that understands type compatibility and allows the
programmer to use the clearest verbs, adjectives, adverbs, nouns and
short camel or underline (as  appropriate)  separators. The reason I use
JAL rather than C (and I have over 20 years C programming experience) on
PIC 16F/18F is that readibility & self documenting code is easier with
it, IMO. But that could be because I have spent too many years doing
Modula-2, Pascal, VB6 and "real" C++ (not just "C" with some classes and
a C++ compiler).

I think a number of people have made very good points (Olin, Vitaliy,
Wouter) and maybe it could be useful to gather all the insightful points
into one document?

There are also 10 kinds of programmers ..  :-)
I despair of the local University or college  actually teaching people
how to program. About 15 to 20 years ago they made some effort. Now they
seem to concentrate on teaching the  Java, C, C++ languages and some x86
and 8051 assembler :-(




2010\06\18@054125 by William \Chops\ Westfield

face picon face
On Jun 17, 2010, at 1:10 PM, Vitaliy wrote:

> why a method that worked spectacularly well for several of our major  
> products, cannot work.

There are lots of "methods" of doing lots of things, that will work  
wonderfully for a particular group of people of particular mindset.  
That doesn't mean that they will scale and continue to work if and  
when the company and/or the projects get bigger.  What one attempts to  
achieve by over-commenting "obvious" code is a superset of what will  
be needed by the next unpredictably composed group of engineers,  
perhaps without ANY guidance from the current group.  "Vitaliy left  
and took his whole group with him, and we still need to add features  
to his code."

To some extent it's impossible.  ISO9000 and the like are predicated  
on the belief that if you just document your processes sufficiently,  
than any group of idiots will be able to continue to make quality  
products at your shop just by following those processes.  But that's  
essentially bogus, because you can't make products with idiots even if  
your process is perfect.

But there ought not be a reason you can take HLL/ExtremeProgramming/
Vitaliy and replace him with ASM/Waterfall/Olin, since both of them  
are very sharp engineers.  You code needs to be documented well enough  
that the next person, who doesn't share your philosophy of what good  
code should look like, will still be able to understand what you have  
done...

BillW

2010\06\18@065152 by Olin Lathrop

face picon face
Michael Watterson wrote:
> I use comments (Block, inline and end of line as appropriate)
> sparingly, and mostly just to explain what isn't evident from code.

Unfortunately most people grossly overestimate what is evident from the
code.  I think that because at the time it's obvious to them.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\18@065906 by Olin Lathrop

face picon face
'William Chops" Westfield ' <@spam@westfw@spam@spamspam_OUTmac.com wrote:
> What one attempts to
> achieve by over-commenting "obvious" code is a superset of what will
> be needed by the next unpredictably composed group of engineers,
> perhaps without ANY guidance from the current group.

Good point.  I hadn't thought of it quite that way before.

Yesterday I responded to one of Vitaliy's posts, and in the process offered
the TCP module of my PIC 18 network stack as a example.  I first tried to
attach it, then noticed it exceeded 100Kbytes, so I renamed it to a .txt
file and put it at http://www.embedinc.com/temp/tcp.txt.  This morning I
found a rejection message from the server complaining about size, so I
probably forgot to remove the attachment.  I don't remember what else I said
in that message, but this 2700 line example of commenting a particularly
complex piece of code is still there.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\18@083143 by Tamas Rudnai

face picon face
> The only thing I know is not to state the obvious (c = a + b)
> but rather comment on what a, b, and C are (self documenting code
> would be useful here).

My argument is not in this part. It does help to understand the code you
wrote if you use descriptive names and labels. What it does not give back is
the intention of the algorithm -- or I can say, it only gives back the
implementation which may or may not the one needs to be done.

As working in reverse engineering full time it is not too hard to understand
very complex obfuscated code to me -- usually with normalising the code and
replacing non-descriptive or obfuscated names to meaningful ones. That part
takes time but let's say that is the most easy thing. What is hard to
understand why did they do this or that, especially if the code is
non-linear.

While a hacker does everything to obfuscate the code, a developer should do
the opposite. They not only should use descriptive names but also should
document why this or that part implemented in the way it was.

With an analogy to a schematics: A normal schematics is just a drawings with
lines and pics of components showing major parameters of the components.
That works okayish, you can make a nice PCB from it and by analysing it you
can figure out most of the design principles if you have the knowledge and
took your time. As opposed when a designer also writes down how the circuit
works, why this or that part was chosen etc etc etc, then it is way easier
to understand, and if you do not understand a part of a circuit from a
drawing, you can read what the designer said about it. Also if you compare
the text with the schematics you may can see mistakes -- text describes
something that was implemented differently or incorrectly, engineer
calculated a value incorrectly etc...

Tamas



On Fri, Jun 18, 2010 at 12:56 AM, Neil Cherry <spamBeGonencherryspamKILLspamlinuxha.com> wrote:

{Quote hidden}

> -

2010\06\18@092035 by Dario Greggio

face picon face
Olin Lathrop ha scritto:
> [...]I think that because at the time it's obvious to them.

I guess I agree completely with you ! :)


--

Ciao, Dario
--
Cyberdyne

2010\06\18@123713 by Dwayne Reid

flavicon
face
At 04:52 AM 6/18/2010, Olin Lathrop wrote:

>Unfortunately most people grossly overestimate what is evident from the
>code.  I think that because at the time it's obvious to them.

Yep - exactly.  I would go one step further and state "I think that
because AT THE TIME it's obvious to them."

Its when you have to dive into that code weeks or months or years
later that you realize how short-sited that was.

dwayne

--
Dwayne Reid   <TakeThisOuTdwayner.....spamTakeThisOuTplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\18@124732 by Dwayne Reid

flavicon
face
At 04:59 AM 6/18/2010, Olin Lathrop wrote:

>Yesterday I responded to one of Vitaliy's posts, and in the process offered
>the TCP module of my PIC 18 network stack as a example.

I have only one minor suggestion, Olin.  Feel free to ignore it <grin>.

When you describe your flag bits such as

tuf_inuse equ    0           ;descriptor is in use

I would add what logic level that is to the end of the comment.  In
other words,

tuf_inuse equ    0           ;descriptor is in use =1

This may not matter to your or your team but much of the code I write
uses both active HI and active LO bits when appropriate.

I suppose that one could make the generalization that you need to
only document odd cases (active LO) but I have found that I catch **
MY ** errors more easily if I document all cases.  It also makes
things easier when I have someone read my code to help me when I'm
debugging something.

Aside from that tiny suggestion, I *really* like the look of the code
example you posted.

dwayne

--
Dwayne Reid   <TakeThisOuTdwaynerKILLspamspamspamplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\18@145527 by Olin Lathrop

face picon face
Dwayne Reid wrote:
> When you describe your flag bits such as
>
> tuf_inuse equ    0           ;descriptor is in use
>
> I would add what logic level that is to the end of the comment.  In
> other words,
>
> tuf_inuse equ    0           ;descriptor is in use =1

My convention is that when the condition is true according to the name of
the flag, then the flag bit value is 1.  If I needed this flag to be the
other way around so that 0 meant it was in use, I'd probably rename it to
say "empty", "unused", "available" or something.

This convention has another benefit in that the code makes more sense when
you read it:

   btfss   flag_inuse    ;skip if unit in use

is a lot less likely to cause errors or confusion than:

   btfss   flag_inuse    ;skip if unit not in use


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\18@161056 by Isaac Marino Bavaresco

flavicon
face
Em 18/6/2010 15:55, Olin Lathrop escreveu:
{Quote hidden}

Sometimes I use the flag inverted, but then I name it with a "not" in
the name, eg. "module_not_in_use" or "ModuleNotInUse", etc.

Isaac

__________________________________________________
Fale com seus amigos  de graça com o novo Yahoo! Messenger
http://br.messenger.yahoo.com/

2010\06\18@161949 by Vitaliy

face
flavicon
face
jim wrote:
> If the code does what it is supposed to do, and there are comments that
> tell
> me important information
> About that code, then I can live with the sloppiness.

I much rather prefer properly written code, that stands on its own.

Vitaliy

2010\06\18@162657 by Vitaliy

face
flavicon
face
Mike snyder wrote:
> Heh, no rocket science this OBDII used by all automotive companies so
> enought people know about it.

You can say the same thing about many other technologies. I don't understand
what you're getting at.


> OBD II is a standard heck there is even
> enough open source software out there to roll your own quickly and
> easily, as always google knows
>
> http://picobdii.googlecode.com/svn/trunk/Code/

That looks familiar. We bought non-exclusive rights to this code from Mr.
Stern back in 2004, but later wrote our code from scratch. I guess he
couldn't find any buyers for his device or the code, so he GPL'ed it. Lesson
learned. :)

Vitaliy

2010\06\18@164513 by Dwayne Reid

flavicon
face
At 04:04 PM 6/17/2010, Vitaliy wrote:
>Dwayne Reid wrote:
> >
> > Which of the above comments would you delete?  Why?
>
>I DON'T PROGRAM IN ASSEMBLY.
>
>Are we clear? :)

Yep - I hear you LOUD and clear <grin>.

I think, then, that we can probably agree on one thing: Its OK to use
lots of comments in assembler code.

One of the reasons I don't consider myself to be a modern programmer
is that I don't write in high-level languages.  I've done stuff in
Turbo Pascal (many years ago) and I don't have any problem with BASIC
(PICbasic, etc) but I don't "get" C programming.  Have a hard time
reading it and certainly can't write it.  My brain just doesn't get it.

Assembler, on the other hand: no problem.  Duck to water kind of
thing.  Started out with PDP-11, went on to Motorola 6800 family, did
a tiny bit of 8051 stuff, done LOTS of PIC assembler stuff.  But as
far as "C" stuff goes - I hire people to write that for me.

dwayne

--
Dwayne Reid   <.....dwaynerspamRemoveMEplanet.eon.net>
Trinity Electronics Systems Ltd    Edmonton, AB, CANADA
(780) 489-3199 voice          (780) 487-6397 fax
http://www.trinity-electronics.com
Custom Electronics Design and Manufacturing

2010\06\18@190706 by Isaac Marino Bavaresco

flavicon
face
Em 18/6/2010 17:25, Vitaliy escreveu:
{Quote hidden}

I'm wondering if he couldn't find a more cumbersome way for testing the
commands.

File <http://picobdii.googlecode.com/svn/trunk/Code/command.c>:

[snip]

       sprintf(cmd,"exit");
       if (strcmp(buff,cmd)==0)
       {
               CommandExit=1;
       }

       sprintf(cmd,"ver");
       if (strcmp(buff,cmd)==0)
       {
          printf("software v%d.%02d",VER_MAJOR,VER_MINOR);
       }        
       sprintf(cmd,"hwver");
       if (strcmp(buff,cmd)==0)
       {
          printf("hardware v%d",HW_VER);
       }        
       sprintf(cmd,"logb");
       if (strcmp(buff,cmd)==0)
       {
               datalog_bin();

       }        
       sprintf(cmd,"vpwmon");
       if (strcmp(buff,cmd)==0)
       {
          vpw_montior();
       }        

[snip]


It the compiler forced him to write this, I would never use it, not even
for free.
And I wouldn't continue testing further after finding the correct string :)


Isaac

__________________________________________________
Fale com seus amigos  de graça com o novo Yahoo! Messenger
http://br.messenger.yahoo.com/

2010\06\18@211036 by Vitaliy

face
flavicon
face
William "Chops" Westfield wrote:
> There are lots of "methods" of doing lots of things, that will work
> wonderfully for a particular group of people of particular mindset.
> That doesn't mean that they will scale and continue to work if and
> when the company and/or the projects get bigger.  What one attempts to
> achieve by over-commenting "obvious" code is a superset of what will
> be needed by the next unpredictably composed group of engineers,
> perhaps without ANY guidance from the current group.  "Vitaliy left
> and took his whole group with him, and we still need to add features
> to his code."

Two comments:

- In agile, they talk about the "project story": the knowledge about a
project that is carried by the project team members. The theory is that,
contrary to popular belief, you cannot transfer the "project story" by
writing it down and handing it to the next team. You can write down the
information, but the next team, if they're starting from scratch, would have
to create their own story.

- I am a believer in the YAGNI (You Aint Gonna Need It) principle. When
you're designing a product or writing documentation, don't create it for
some hypothetical user or to solve a hypothetical problem in the future.
Create it to solve real problems for real users, now.

Language is not a perfect or terribly efficient means of transferring
information, which is why Olin, Gerhard and others misunderstood it when I
tried to explain it last time.

I'm not against documentation or comments. I'm against wasting time creating
unnecessary comments (and "over-commenting" can be taken to mean that).


> To some extent it's impossible.  ISO9000 and the like are predicated
> on the belief that if you just document your processes sufficiently,
> than any group of idiots will be able to continue to make quality
> products at your shop just by following those processes.  But that's
> essentially bogus, because you can't make products with idiots even if
> your process is perfect.

The bureaucrats think quality can be legislated, you just need to have
enough rules and documentation.


> But there ought not be a reason you can take HLL/ExtremeProgramming/
> Vitaliy and replace him with ASM/Waterfall/Olin, since both of them
> are very sharp engineers.  You code needs to be documented well enough
> that the next person, who doesn't share your philosophy of what good
> code should look like, will still be able to understand what you have
> done...

I agree, but that person needs to be "real". You have to assume a certain
level of competence and knowledge of the subject matter.

Vitaliy

2010\06\18@211637 by Vitaliy

face
flavicon
face
Dwayne Reid wrote:
>> > Which of the above comments would you delete?  Why?
>>
>>I DON'T PROGRAM IN ASSEMBLY.
>>
>>Are we clear? :)
>
> Yep - I hear you LOUD and clear <grin>.
>
> I think, then, that we can probably agree on one thing: Its OK to use
> lots of comments in assembler code.

Probably. I mean, the low-level stuff for sure.

However, if you have the time, pick up a copy of "Code Complete" and read
the chapter where it talks about "programming into a language". You can
simulate HLL/OOP constructs, apply the "loose coupling, tight cohesion"
rule, etc.


> One of the reasons I don't consider myself to be a modern programmer
> is that I don't write in high-level languages.  I've done stuff in
> Turbo Pascal (many years ago) and I don't have any problem with BASIC
> (PICbasic, etc) but I don't "get" C programming.  Have a hard time
> reading it and certainly can't write it.  My brain just doesn't get it.

I probably could learn assembly, but I'm sure it would take considerable
effort and special motivation.


> Assembler, on the other hand: no problem.  Duck to water kind of
> thing.  Started out with PDP-11, went on to Motorola 6800 family, did
> a tiny bit of 8051 stuff, done LOTS of PIC assembler stuff.  But as
> far as "C" stuff goes - I hire people to write that for me.

Don't see nothing wrong with that.

Vitaliy

2010\06\18@212238 by Vitaliy

face
flavicon
face
Dwayne Reid wrote:
>>Unfortunately most people grossly overestimate what is evident from the
>>code.  I think that because at the time it's obvious to them.
>
> Yep - exactly.  I would go one step further and state "I think that
> because AT THE TIME it's obvious to them."
>
> Its when you have to dive into that code weeks or months or years
> later that you realize how short-sited that was.

Haven't had this happen to me recently, which tells me that the level of
comments is adequate.

One time after the switch, I had to go back to old-style code and make a
change, and the mess hurt my eyes. Instead of simply wading through the code
until I could understand what it does, I started refactoring it. A
super-function several pages long was split up and reduced to a few function
calls.

When the refactoring was done, making the change was quick and easy. And I
had a sense of satisfaction, because I left the code in better shape than I
found it.

Vitaliy

2010\06\18@220523 by RussellMc

face picon face
> I would add what logic level that is to the end of the comment.  In
> other words,
>
> tuf_inuse equ    0           ;descriptor is in use =1

1.      FWIW (not much by Olin's assessment probably :-) ) I use
variable names whose state and general type is implicit (to me).
Vague shades of ancient FORTRAN :-)  (which I only ever used as a
student I hasten to add :-) ).

This means that at a glance you can tell whether a 'designator' refers
to a variable or a constant or a 'flag' or ... and if a binary
conditional test value, whether the pass state is set or clear.

Thus eg any "load immediate" type instructions are liable to operate
of designators beginning with K (YNMV) and anything that operates on
kXXXXX that treats it in any way as a variable is highly suspect, at
best (except in Apple II BASIC :-) * ).

Rigorously implemented, such a scheme allows a useful degree of
brain-time error parsing.
Non rigorously implemented it helps to add to the rich tapestry of life.

2.      In the spirit of Vitaliy's offerings to date I offer no
examples and assert that all competent people should be able to
utilise this system without further ado.

Alas, having read this thread with interest so far, I find I'm not up
to the challenge of extracting especially useful input from what
Vitaliy has disclosed. He seems to be saying that if you name your
variables correctly (or perhaps do some other clever thing that I'm
unable to ascertain)  then one needs only write, typically, one
comment per 100 lines of HLL code. As many functions / subroutines /
... would in many cases be under to well under 100 lines of HLL code
this means that many or even most such would contain no comments at
all. A truly remarkable achievement.

3.  I find that, by dint of prodigious commenting levels by most
standards, that I can essentially immediately understand code that I
wrote over a decade ago for my own purposes. ie Such commenting is
entirely for my use. Nobody else by any reasonable expectation would
need or want  to be able to understand such code. (But I'd expect that
what is meant to serve as a guide  for me would be meaningful to
others).

If others methods can achieve the same or better results and less
effort it would be excellent to know enough about them to allow their
reliable implementation.




           Russell

2010\06\18@232447 by Marechiare

picon face
< He seems to be saying that if you name your variables
> correctly (or perhaps do some other clever thing that I'm
> unable to ascertain)  then one needs only write, typically,
> one comment per 100 lines of HLL code.

He seems to be a master of coding right things in a way that many
would struggle understand it. Instead of adding comments to his
message, let's just try to re-factor it :-)

The higher level of programming language -  the more it resembles
human language. If you can express some algorithm in Chinese, but you
can't grasp Chinese natively, what would you do to assure you and
other folks could grasp the algorithm later - yes, you would add
comments in English.

His point, as I see it, is - do not over-stuff you Chinese code with
English comments. Better try learning how to express things in Chinese
clearly and concisely (not necessarily on a native level), after you
mastered the style, you, probably, won't need adding English comments
at all :-)

2010\06\19@024053 by Oli Glaser

flavicon
face


--------------------------------------------------
From: "Marechiare" <RemoveMEmarechiarespamspamBeGonegmail.com>

> His point, as I see it, is - do not over-stuff you Chinese code with
> English comments. Better try learning how to express things in Chinese
> clearly and concisely (not necessarily on a native level), after you
> mastered the style, you, probably, won't need adding English comments
> at all :-)

If we have to have an analogy, I think a slightly better one would be that
the comments are akin to brief explanatory notes on a scene from Shakespeare
or a clause in a legal document. The point being both Shakespeare and legal
documents *are* written in a language one can understand, but the meaning
can still be obscure, at least for a while (the *actual* language in
question is irrelevant here, save to say the technical stuff *and* comments
are both written in the same). Comments/Notes help to clarify things quickly
and easily.

I have also watching this thread with interest, and trying to keep an open
mind, hoping to learn something as I think my programming skills could
certainly use some improvement. However, I have to say I can't really see
any difference between "self documenting code" and intelligently named
functions and variables so far, which still need comments to go with them
most of the time. I really would like to see an example of 200 lines with
only one comment. I'm still keeping an open mind. Failing more code
examples, a clear set of guidelines would be useful.

I write in assembly, C, C++, C# and VB, and I comment a *lot* in all of
them. It hardly takes any time (it's not as if I code as fast as I can type
anyway), and always helps me when reviewing stuff at a later date (and
hopefully does anyone else who uses it). As far as comments for others go -
I recently adapted a largish windows app and if the original author had not
commented well (and used doxygen to make things even easier) I'm pretty sure
it would have taken me at least twice as long.




2010\06\19@073616 by Marechiare

picon face
>> His point, as I see it, is - do not over-stuff you Chinese
>> code with English comments. Better try learning how
>> to express things in Chinese clearly and concisely (not
>> necessarily on a native level), after you mastered the
>> style, you, probably, won't need adding English comments
>> at all :-)
>
> If we have to have an analogy, I think a slightly better one
> would be that the comments are akin to brief explanatory
> notes on a scene from Shakespeare or a clause in a legal
> document. The point being both Shakespeare and legal
> documents *are* written in a language one can understand,
> but the meaning can still be obscure, at least for a while
> (the *actual* language in question is irrelevant here, save
> to say the technical stuff *and* comments are both written
> in the same). Comments/Notes help to clarify things quickly
> and easily.

I don't think the analogy is valid: "brief explanatory notes on a
scene from Shakespeare" are not comments to code we were talking
about. These "brief explanatory notes" are the code itself. They are
elaborative instructions to actors how to act. The legal doc, perhaps,
I would agree, if I got a clue somehow what the doc it was.


{Quote hidden}

200 lines can be 20 properly named objects/methods etc, well self explanatory.


> I write in assembly, C, C++, C# and VB, and I comment
> a *lot* in all of them. It hardly takes any time (it's not as if
> I code as fast as I can type anyway), and always helps
> me when reviewing stuff at a later date (and hopefully
> does anyone else who uses it). As far as comments for
> others go - I recently adapted a largish windows app and
> if the original author had not commented well (and used
> doxygen to make things even easier) I'm pretty sure
> it would have taken me at least twice as long.

Yes, good comments can be very helpful.

2010\06\19@082945 by RussellMc

face picon face
Summary:

A number of people are clearly prepared to put some effort into
understanding what's involved* in Vitaliy's method. And it's clear
that ALL such people are confused. It would be immensely useful if you
(Vitaliy) would provide a clear point by point exposition of your
claims and method so that others can benefit. Failure to do so does
not mean that the 'method is a phantasm (although it does mean that it
could be) but that it 'needs-must' be relegated to the area of
essentially unsupported religious assertion. Decent explanation may
win many converts :-).

_________

As an example of recent comments on Vitaliy's method, from a single post -

{Quote hidden}

It is COMPLETELY clear from this and other comments that Vitaliy has
not clearly proposed a new and radical paradigm shift in how to write
good code in a manner that is usefully meaningful to intelligent
people keen to learn*. He may well HAVE one, it may well actually
work, but if nobody so far has seen the light of day, despite a number
of people trying hard to  do so*, then either his explanations are
inadequate, or the method is obscure and approached only by
circumlocution and trial by fire, or there is none. Of these, the
first seems most likely - ie there has been no clear succinct well
identified exposition of the method. We instead have N blind engineers
trying to identify Vitaly's elephant and coming iup with a range of
overlapping but different answers. Vitaliy can either explains this as
being due to the stupidity of the herd, or conclude that he needs to
explain things more clearly and completely. (Or note that this is true
religion for the sincere devotee to find by following the path to
wisdom and enlightenment.)(This also doesn't mean the method doesn't
work - just places it in the same class as other 'believe me, you'll
never go back" claims.)

Many people are clearly prepared to put some effort into understanding
what's involved*. It would be immensely useful if you (Vitaliy) would
provide a clear point by point exposition of your claims and method so
that others can benefit.

* We KNOW that a number of clever people are trying hard to understand
what this is about, because they have said so. Saying that the inertia
of the system is blinding people to  seeing the new promised way is
not good enough - one must either conclude that the explanations are
lacking or declare those claiming to be seekers to be liars. Choose
which :-). Explanation expected any time now :-). Thanks.


        Russell

2010\06\19@112510 by jim

flavicon
face
All,

It appears to me that for every person on this list, and even every
programmer everywhere, regardless of what language or platform, has their
own ideology and preferences as to whether to comment or not, and if so, how
much and what style.

Further, it appears to me that any one person isn't necessarily going to
convince another person that his or her methods are superior, and cause them
to convert.

With that said, it seems logical (IMHO) to say that we all agree to
disagree, and leave it at that.   There has been much discussion with very
little forward motion as I see it, so why not call it a draw, and move on to
something else?

Regards,

Jim  

{Original Message removed}

2010\06\19@115413 by RussellMc

face picon face
> Further, it appears to me that any one person isn't necessarily going to
> convince another person that his or her methods are superior, and cause them
> to convert.

> With that said, it seems logical (IMHO) to say that we all agree to
> disagree, and leave it at that.   There has been much discussion with very
> little forward motion as I see it, so why not call it a draw, and move on to
> something else?

I'm afraid that that makes no sense to me wrt finding out about
something different/.
.
A small but significant body of people have indicated a willingness to
hear about new ideas and to be able to try them for themselves.
These people are NOT trying to disagree, so agreeing to disagree makes no sense.

While we  could all make up our own versions of a more minimalist
commenting style, Vitaliy reports a truly revolutionary variation in
what is traditional lore and general experience and what he finds
workable. One comment per 100 lines is so different  from the norm as
to be paradigm breaking.

What is lacking is a description of what exactly this new system is.
Within the one  post that I quoted we find 4 people trying to explain
what they have heard - and all differ. What is required is not
something to disagree ABOUT but enough details to agree on.

Inquiring minds want to know. No?

                   R

2010\06\19@141409 by jim

flavicon
face
Russell,

What you say makes perfect sense.  The real question is when and if this
revolutionary system ever gets described in such a manner and with enough
detail to allow anyone who chooses to adopt it, to adopt and use it.   As
you say, that description, and those details, are yet to come.
So, I guess I'll just wait quietly and wait for such description and
details, if they ever do materialize.  At that point in time, I'll then make
up my mind whether or not this new system is as revolutionary as advertised.
In the meantime, I'll remain quiet wrt this subject.

But in the past, there have been several instances when a thread goes on ad
nauseum without gaining any real benefit to the the list or it's
constituents.  And I am sort of surprised one of the admins haven't said
something about it already.   But that's not my call.  It's just an
observation.


Regards,

Jim

{Original Message removed}

2010\06\19@160145 by Olin Lathrop

face picon face
Vitaliy wrote:
> - In agile, they talk about the "project story": the knowledge about a
> project that is carried by the project team members. The theory is
> that, contrary to popular belief, you cannot transfer the "project
> story" by writing it down and handing it to the next team. You can
> write down the information, but the next team, if they're starting
> from scratch, would have to create their own story.

So the answer is "screw, ain't gonna work anyway so don't bother"?

> - I am a believer in the YAGNI (You Aint Gonna Need It) principle.
> When you're designing a product or writing documentation, don't
> create it for some hypothetical user or to solve a hypothetical
> problem in the future. Create it to solve real problems for real
> users, now.

Then you are stuck when the unforseen real problem pops up in the future.
Experience has shown us this will happen, and we even have some idea what
kinds of problems are likely to pop up in the future and how to address them
now to keep the cost down later.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\19@161431 by Olin Lathrop

face picon face
jim wrote:
> But in the past, there have been several instances when a thread goes
> on ad nauseum without gaining any real benefit to the the list or it's
> constituents.  And I am sort of surprised one of the admins haven't
> said something about it already.   But that's not my call.  It's just
> an observation.

We do seem to be going in circles, but so far nobody has mentioned anything
about Vitaliy's mother's army boots, so I don't see a reason for the admins
to get envolved.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\19@180233 by Oli Glaser

flavicon
face


--------------------------------------------------
From: "Marechiare" <spamBeGonemarechiare@spam@spamspam_OUTgmail.com>
Sent: Saturday, June 19, 2010 12:36 PM
To: "Microcontroller discussion list - Public." <TakeThisOuTpiclistspamspammit.edu>
Subject: Re: [PIC] Structuring Assembly Code

{Quote hidden}

Of course not - they are an analogy of.

> These "brief explanatory notes" are the code itself. They are
> elaborative instructions to actors how to act. The legal doc, perhaps,
> I would agree, if I got a clue somehow what the doc it was.

It doesn't matter which legal document it is. The point is the same - that
although one can understand the individual words/commands in a language, the
overall "meaning" may still be unclear. With the Shakespeare, I was thinking
more of the notes written for students in a text book to help them
understand what is happening more easily - they are (hopefully)written in a
clear and concise manner. Analogies are not that necessary here anyway,
comparisons maybe - look at work in many fields and there is usually some
method of "commenting" involved, for good reason.


{Quote hidden}

That's part of what I was saying - that "self documenting/explanatory code"
would need to be (at least in my view), more than just properly named
objects and methods. Comments are still necessary.


{Quote hidden}

Exactly.


2010\06\19@180833 by sergio masci

flavicon
face

Ok, well as some people seem genuinely interested in pursuing this, I'm
going to try HARD to explain why easier to follow code with fewer comments
is a good thing. I'm not going to contrive some artificial code that makes
my point but is unrealistic in the real world, instead I'm going to look
at some real code posted by a piclister. Aplogies in advance to Byron Jeff
as it is not my intention to belittle his abilities.

So here goes:


On Wed, 16 Jun 2010, Byron Jeff wrote:

{Quote hidden}

in my opinion a better comment here would be

       ; return arr[month-1]

"month" should already be documented as being in the range 1-12 and it's
use should be consistant throughout the program.

Also changing:
       addlw        255

to
       addlw        -1

would make the code that much easier to follow


> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
>
> Taking another look at the comment, I forgot to note that the values are
> the number of minutes offset from 5AM for sunrise and 5PM for sunset
> respectively. Also that this system does not try to account for Daylight
> Savings time and runs all year in Standard Time.
>
> Even the small comment in the routine describes why the addlw 255 is
> there.

Again I disagree with the need for this comment and would have prefered
the use of

       addlw        -1

{Quote hidden}

Right so the above comment IMO is VERY good. My only complaint would be
that the reader needs to work through the code to get to it. It would be
really useful if there were a seperate document that gathered esential
details like this together in one place so that the reader could get a
feel for what to expect before he/she starts ploughing through the code.
Having this all in one place would be like having a picture of a finished
jigsaw and a pile of pieces. Without it, well it's much much harder.

{Quote hidden}

Personnaly I would have written "sunset" differently so that I could make
it's use a little easier to follow

e.g.

sunset
       addlw        -1
       addwf        PCL,F                ; return sunset_arr[w-1]

sunset_arr
       dt        40,69,94,118,141,163,172,158,123,82,45,29,40


setset        
       movf        month,W
       addlw        1
       call        sunset                ; get sunset_arr[month+1]
       movwf   sunnext

       movf        month,W
       call    sunset                ; get sunset_arr[month]
       movwf   sunoff

and if we had changed the name of the subroutine "sunset" to something a
little more descriptive, then the above comments would have been redundent
as well

{Quote hidden}

This is so frustrating :-|

You put in comments like "shift" and "Ditch the rest" which are
sooooo redundent because they repeat exactly what the instructions
they are attached to explicitly state, yet more complex stuff you
just skip over. I mean, what does "interpolate" mean.

I would have commented the "interp" subroutine above as follows:


; function: Interpolate the sunrise/sunset time
;
; inputs: sunoff/sunnext/sunhour
; outputs: sunhour/sunmin
;
;
; This function performs a multiplication of a fixed point number
; with an integer

; The fixed point number is 8 bits wide and in the format III.FFFFF
; The integer is 8 bits wide

; The multiplication is performed by repeated addition. We use the
; integer argument as the count and we repeatedly add the fixed point
; number to an 8 bit accumulator. We make sure that the accumulator
; does not overflow by keeping the integer part of the accumulator
; seperate from the fractional part. We do this by adding or subtracting
; it from the original offset and then remove it from our running sum

interp
       movf        sunoff,W        ; sunnext = difference between current month
       subwf        sunnext,W        ; and next month

       movwf        sunsign
       btfsc        sunsign,7
       sublw        0
       movwf        sunnext                ; sunnext = abs(sunnext)


; perform the multiplication by doing repeated addition

       clrf        sunfract
       movf        day,W
       addlw        -1
       btfsc        STATUS,Z
       goto        sscont2
       movwf        c1

       ; for c1=day-1; c1!=0; c1--

ssloop  movf    sunnext,W
       addwf   sunfract,W
       movwf   sunfract        ; accumulate integer and fractional parts
                               ; of fixed point calc together

       movwf        tempw
       rrf        tempw,F
       swapf        tempw,W
       andlw        7                ; w = integer part only


       btfsc   sunsign,7
       sublw   0

       addwf   sunoff,F        ; accumulate integer part of fixed point calc
                               ; (add if sunsign >= 0, subtract if sunsign < 0)

       movlw   0x1f
       andwf   sunfract,F        ; keep integer and fractional parts seperate

       decfsz  c1,F
       goto    ssloop


Here I've kept the code the same tried to reduce the number of comments to
highlight the more important details.

================================


Now that I've worked my way through the code (not the comments)
I can see what the code is trying to do is:

       temp     = abs(sunnext - sunoff) * (day-1)

       sunfract = temp & 0x1f
       temp     = temp >> 5

       if (sunnext - sunoff < 0 then
               temp = -temp
       endif

       sunoff   = sunoff + temp

================================

What I actually want to do now is change the code to make it easier to
follow, reduce the need for comments and improve the development tool's
(assembler in this case) ability track inconsistant changes later on.

So putting this back into assembly we get:

; ***        temp = abs(sunnext - sunoff)

       clrf        temp+1
       movf        sunnext,w
       subwf        sunoff,w
       movwf        temp+0

       BYTE_ABS temp+0

; ***        temp = abs(sunnext - sunoff) * (day-1)

       decf        day,w
       WORD_MULTIPLY_BY_W temp


; ***        sunfract = temp & 0x1f

       movf        temp+0,w
       andwl        0x1f
       movwf        sunfract

; ***        temp = temp >> 5

       WORD_RIGHT_SHIFT_5 temp

; ***        if (sunnext - sunoff < 0)

       movf        sunnext,w
       subwf        sunoff,w
       andlw        0x80
       bz        lab_else        

       ; got here if (sunnext - sunoff < 0)

; ***        temp = -temp

       WORD_NEGATE temp

lab_else

; ***        sunoff = sunoff + temp

       movf        temp+0,w
       addwf        sunoff

================================

removing redunent comments we get

; ***        temp = abs(sunnext - sunoff)

       clrf        temp+1
       movf        sunnext,w
       subwf        sunoff,w
       movwf        temp+0

       BYTE_ABS temp+0

; ***        temp = abs(sunnext - sunoff) * (day-1)

       decf        day,w
       WORD_MULTIPLY_BY_W temp

       movf        temp+0,w        ; extract fraction
       andwl        0x1f
       movwf        sunfract

       WORD_RIGHT_SHIFT_5 temp        ; extract integer

; ***        if (sunnext - sunoff < 0)

       movf        sunnext,w
       subwf        sunoff,w
       andlw        0x80
       bz        lab_else

       WORD_NEGATE temp

lab_else

       movf        temp+0,w
       addwf        sunoff

       return

Now this might only be 90% as efficient as the original but I would argue
that it's a lot easier to understand even with much fewer comments.

The point here is that we have reduced the noise so we can FOLLOW the code
manually and automatically (even using our development tools) much more
easily.

Now someone will stand up and shout "that's cheating, you've just moved a
bunch of code into macros". Well it's not cheating because now what we've
actually done is encased each of the fragments in a special wrapper that
the particular development tool we are using (in this case the assembler)
actually understands. We have created a link between our understanding of
a section of code and the tool's handling of it. In this case the link is
a symbolic name (the macro name) which actually means something to us and
allows the tool to track its use. If we change the code's meaning, we
would change the name of the link (the macro's name), and the tool would
then warn us if we failed to update everywhere in the code where we are
trying to use this fragment of code.

I know this sounds obvious but what doesn't seem to be getting through is
that the symbolic name has made it much easier for the reader to follow
the code and has removed the need for low level comments.

If we just used the fragments of code inline, the tool would miss changes
made to one fragment which have a knock on effect in others even though
the comments clearly show a dependency.

For completenes I include a definition of the macros I've used above.

;-----------------------

BYTE_ABS .macro        arg

       btfsc        (arg),7
       comf        (arg)

       .endm
       

skip_z        .macro

       btfss        STATUS, Z

       .endm


skip_nz        .macro

       btfsc        STATUS, Z

       .endm


skip_nc        .macro

       btfsc        STATUS, C

       .endm


bz        .macro        arg

       skip_nz
       goto        arg        

       .endm


bnz        .macro        arg

       skip_z
       goto        arg        

       .endm


WORD_MULTIPLY_BY_W        .macro        arg

       movwf        mult_arg2

       clrf        mult_acc+0
       clrf        mult_acc+1

       tstf        mult_arg2
       bz        wmult_end

wmult_loop
       movf        (arg)+0,w
       addwf        mult_acc+0

       skip_nc
       incf        mult_acc+1

       movf        (arg)+1,w
       addwf        mult_acc+1

       decfsz        mult_arg2
       goto        wmult_loop

wmult_end

       movf        mult_acc+0,w
       movwf        (arg)+0

       movf        mult_acc+1,w
       movwf        (arg)+1

       .endm


WORD_NEGATE        .macro        arg

       movlw        0xff
       xorwf        (arg)+0
       xorwf        (arg)+1

       incf        (arg)+0

       skip_nz
       incf        (arg)+1

       .endm


WORD_RIGHT_SHIFT        .macro        arg

       bcf        STATUS, C
       rrf        (arg)+1
       rrf        (arg)+0

       .endm


WORD_RIGHT_SHIFT_5        .macro        arg

       WORD_RIGHT_SHIFT arg
       WORD_RIGHT_SHIFT arg
       WORD_RIGHT_SHIFT arg
       WORD_RIGHT_SHIFT arg
       WORD_RIGHT_SHIFT arg

       .endm


>
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
>
> It's not self commenting. And the comments are not unnecessary. In fact
> looking at it 10 years later, it's a pretty good use of a fixed point
> algorithm. But I wouldn't even want to try to figure out how it worked
> without the comments.

The reason you are finding it so easy to follow your code after 10 years
is because YOU wrote the comments and reading them again is causing
YOU to remember what your intension was when you wrote the code. In some
places these comments are too short and obvious to be anything other
than a nmemonic - an aid to help you remember. They would not have the
same effect on someone else and in many cases they would hamper someone
else's homing in on the more relevent information.

>
> And that's the point Olin is trying to make.

Maybe, but I still don't agree with it.

Friendly Regards
Sergio Masci

2010\06\20@082637 by Olin Lathrop

face picon face
sergio masci wrote:
> "month" should already be documented as being in the range 1-12 and
> it's use should be consistant throughout the program.

If anything, month should be 0-11 consistantly except when it's coming or
going to a user interface.  The same goes for days within a month, hours
within a day, etc.  This makes internal computations more natural.  It is
only our human convention that numbers January as 1.

> Also changing:
> addlw 255
>
> to
> addlw -1
>
> would make the code that much easier to follow

You might have to say ADDLW LOW -1 to avoid a warning.

In any case, I think you're right, but that's really a minor nit.  I doubt
anyone's code would stand up to that level of nitpicking.

> It would be
> really useful if there were a seperate document that gathered esential
> details like this together in one place so that the reader could get a
> feel for what to expect before he/she starts ploughing through the
> code.

Separate documents get out of sync too easily.  If there is a separate
document, it should only be a general introduction to the structure of the
code.  Details should stay with the code, and only with the code.

It's funny you didn't mention the one thing that I think is a real problem
with Byron's code.  The bug waiting to happen is that he's using ADDWF PCL
to index into a call table without any mechanism to guarantee there won't be
a 256 word boundary there or even a comment warning someone that this must
be manually ensured.  Unless you're really really tight on cycles or space,
do the extra math to make sure PCLATH is set right.

In a few cases where I was tight on cycles, I put the table at a fixed
address and let the linker place other modules around it.  Since that was
the only section forced to a particular address other than the reset vector
and the interrupt routine, it was no big deal for the linker to still use
the code space efficiently.

> I mean, what does "interpolate" mean.

That's a standard english word that was quite legitimate for Byron to assume
the reader knows.  It's also common in computer science, and is often used
to describe the process of computing a blended value between two known
points when you know how far between them you are.  Look it up.  I don't
mean that as a flip comment, just that this has a standard meaning and it's
out there to easily find.

> So putting this back into assembly we get:

Yucc.  The lack of formatting makes this really painful to look at.  You'd
also get massive warning if you tried to assemble this.

> Now someone will stand up and shout "that's cheating, you've just
> moved a bunch of code into macros".

That's legitimate sometimes, but there's also a tradeoff.  The more macros,
the more non-standard your language becomes.  They can make things clearer,
but they also take time to look at, make sure they really do what is
claimed, check what corner cases are really handled and which ones are
assumed to not be presented, etc.

> BYTE_ABS .macro arg
>
> btfsc (arg),7
> comf (arg)
>
> .endm

If you want to pick apart Byron's code, you should at least use the same
language he did.  I don't know what this is, but it's not MPASM since that
doesn't have directives ".macro" and ".endm".  ASM30 does, but this is
clearly not the dsPIC instruction set.

Also it seems you have a bug.  The reason I can only say "seems", is that
you haven't defined what the BYTE_ABS macro is supposed to do exactly.  From
the name I can only assume that you intend it to take the absolute value of
ARG.  Note that while the name might be reasonably clear about the
arithmetic operation, it says nothing about where the result should go.
This should all be clearly described in the header comments of the macro.
For example, it could be just as legitimate to have the macro leave the
result in W.

As for the bug, to do a twos complement negate requires a complement and
increment, not just a complement.  Therefore your macros is seriously
broken.  If you really meant it to do ABS in something other than twos
complement, this should have been clearly documented.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\20@120038 by sergio masci

flavicon
face


On Sun, 20 Jun 2010, Olin Lathrop wrote:

> sergio masci wrote:
> > "month" should already be documented as being in the range 1-12 and
> > it's use should be consistant throughout the program.
>
> If anything, month should be 0-11 consistantly except when it's coming or
> going to a user interface.  The same goes for days within a month, hours
> within a day, etc.  This makes internal computations more natural.  It is
> only our human convention that numbers January as 1.

I was trying NOT to critisise his desicion for using a specific range but
to show that if he was consistant about it's use that some of his comments
would have been stating the obvious (within the bounds of his code) and
therefor redundent.

Yes I rarely use anything that has a range starting at one EXCEPT
enumerated constants where zero is reserved for an illegal value.

{Quote hidden}

I wasn't nitpicking. I was trying to show how the comment could be
simplified (and thus made redundent) by moving the -1 from the comment to
the actual code.

{Quote hidden}

Yes I saw this but felt it was a distraction. If I'd added a comment here
it wouldn't have helped the assembler pick up on the problem and it
wouldn't have helped anyone debugging the code unless they stumbed across
the comment. If someone had added a few instructions much lower (towards
zero) in the code that caused the tables to be pushed across a page
boundery, the developer would have spent time looking at the instructions
added and only extended his search later. The chances of stumbing across
the comment initially would have been slim.

Yes I understand what you mean about doing a full address calc using
PCLATH. But it wasn't my intention to make Byron's existing code bullet
proof, just to discuss "easy to follow reduced comment code".

{Quote hidden}

Yes I know the majority of piclisters will understand what interpolate
means. My point was that there are many other words and functions that
even a moderately competent programmer should understand without the need
to spell them out. So if you're going to explain something, explain the
complicated stuff and leave the simple commonly understood stuff alone.

>
> > So putting this back into assembly we get:
>
> Yucc.  The lack of formatting makes this really painful to look at.  You'd
> also get massive warning if you tried to assemble this.

Sorry I tried to format it using fixed width font and tabs.

I haven't tried to assemble this using MPLAB so I don't know what warnings
or errors I'd get. I'm sure it wouldn't be that hard to get it to assemble
without errors or warning though :-)

>
> > Now someone will stand up and shout "that's cheating, you've just
> > moved a bunch of code into macros".
>
> That's legitimate sometimes, but there's also a tradeoff.  The more macros,
> the more non-standard your language becomes.  They can make things clearer,
> but they also take time to look at, make sure they really do what is
> claimed, check what corner cases are really handled and which ones are
> assumed to not be presented, etc.

Granted, but once you get into the swing of it, it gets very much easier
because you develope a style. You end up defining a convention. Reading
and writing code, following a logical (to you) convention makes things
easier.

{Quote hidden}

granted it's not MPASM but there is enough information there for the
average piclister to understand that these statements define a macro.

>
> Also it seems you have a bug.  The reason I can only say "seems", is that
> you haven't defined what the BYTE_ABS macro is supposed to do exactly.  From
> the name I can only assume that you intend it to take the absolute value of
> ARG.

well caught! And this couldn't have illustrated my point better if I had
deliberately contrived it.

The fact that this fragment of code (the entire fragment!) has been tagged
(in this case encased in a macro) with a meaningfull name, has caused the
reader to see an error in that code.

Yes there is a bug, but the bug is not there because I placed the code in
a macro. The bug would have still been there if the code had been placed
inline in the "interp" subroutine.

>  Note that while the name might be reasonably clear about the
> arithmetic operation, it says nothing about where the result should go.
> This should all be clearly described in the header comments of the macro.
> For example, it could be just as legitimate to have the macro leave the
> result in W.

Yes I agree but consider that I was trying to make a point and present a
complete implentation. Once you get into the swing of it and your style
emerges you will be able to understand how a particular macro works by
looking at its name and the aguments supplied - in the same way you get
used to seeing the "lw" or "wf" suffix's on a PIC opcode.

You might develope a naming convention where part of the name indicates
the macro operates on 16 bit words or 8 bit bytes (as I did in my example)
i.e.
       WORD_xxxx
       BYTE_xxxx

>
> As for the bug, to do a twos complement negate requires a complement and
> increment, not just a complement.  Therefore your macros is seriously
> broken.  If you really meant it to do ABS in something other than twos
> complement, this should have been clearly documented.

You are right it was trying to do an ABS and it was broken and you helped
show how a reader was able to find the bug WITHOUT a comment :-)

Thank you for your input.

Friendly Regards
Sergio Masci

P.S. I don't use MPASM I use XCASM

2010\06\20@142038 by Olin Lathrop

face picon face
sergio masci wrote:
> You are right it was trying to do an ABS and it was broken and you
> helped show how a reader was able to find the bug WITHOUT a comment
> :-)

It would have been easier and quicker with a good comment.  I would have
spent less time deciding it was a bug if there was a comment clearly stating
this macro is supposed to do a twos complement negate on a memory location.
Without the comment I had to look around more before deciding it was
probably a bug.  With the comment I would have know quickly it was
definitely a bug.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\20@164938 by William \Chops\ Westfield

face picon face

On Jun 20, 2010, at 1:04 PM, sergio masci wrote:

> stating the obvious

Ah; I think I begin to see.  The following three lines of code do the  
same thing, but are of increasing "goodness" due to meaning being  
moved from comments to code.  The first line is somewhat typical.  The  
second line uses a more meaningfully name temporary variable and  
recasts the constant as hex to make the bits used more obvious.  And  
the third line pretty much says everything that needs to be said,  
without a comment (but you need to have written a trustworthy macro or  
subroutine at some point.  Some people would claim that this goes too  
far.)

       c = pak.iphdr.saddr & 192;   /* mask upper bits to get network class */
       netclass = pak.iphdr.saddr & 0xC0;  /* get network class */
       netclass = GET_NETWORK_CLASS(pak);

BillW

2010\06\20@165234 by Marechiare

picon face
> The point is the same - that although one can understand
> the individual words/commands in a language, the overall
> "meaning" may still be unclear. With the Shakespeare, I
> was thinking more of the notes written for students in a text
> book to help them understand what is happening more
> easily - they are (hopefully)written in a clear and concise
> manner.

I do appreciate your sense of humor :-)  "A clear and concise" resume
of what's, say, "Hamlet" is about. "To be or not to be; that's the
question." - can you really "clearly and concisely" explain what's the
phrase is about? It has been known for  centuries there is no such
explanation. Comments, even the most clear and concise can be
misleading.


>> 200 lines can be 20 properly named objects/methods etc,
>> well self explanatory.
>
> That's part of what I was saying - that "self documenting/
> explanatory code" would need to be (at least in my view),
> more than just properly named objects and methods.
> Comments are still necessary.

Yes, they are necessary, but not necessarily within those elementary
20 properly named methods. A good header block of comments for the
entire object probably can do the job.

2010\06\20@171527 by Olin Lathrop

face picon face
'William Chops" Westfield ' <westfwEraseMEspammac.com wrote:
> Ah; I think I begin to see.  The following three lines of code do the
> same thing, but are of increasing "goodness" due to meaning being
> moved from comments to code.  The first line is somewhat typical.  The
> second line uses a more meaningfully name temporary variable and
> recasts the constant as hex to make the bits used more obvious.  And
> the third line pretty much says everything that needs to be said,
> without a comment (but you need to have written a trustworthy macro or
> subroutine at some point.  Some people would claim that this goes too
> far.)
>
> c = pak.iphdr.saddr & 192;   /* mask upper bits to get network class
> */ netclass = pak.iphdr.saddr & 0xC0;  /* get network class */
> netclass = GET_NETWORK_CLASS(pak);

This is yet another example of the fallacy of "self documenting" code.  The
author thinks everything is obvious, so doesn't bother to explain it
further.  Big mistake, and bad programming.

I don't like the third line because now you have to go chasing around to see
what GET_NETWORK_CLASS really does.  But even if that is truly obvious and
trusted, then a opportunity has been wasted to explain why you are getting
the network class, or from where.  What is PAK, our address, some server's,
our netmask, any of a 100 other possibilities?  Why do we care what it's net
class is?

No matter what information you think a bare line of code conveys (and keep
in mind it very rarely conveys as much as you think at the time), that
information has to end somewhere.  Wherever that is, the comment is a great
place to illuminate the next level up of information.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\20@212428 by RussellMc

face picon face
Understanding that this is intended to be an example that crosses a
(possible) boundary.
Understanding also that this is a "straw man". Better would be a real
world example provided for critiquing by exponents of the art. Alas
these are a bit thin on the ground at present so examples will have to
do for now:

>> And the third line pretty much says everything that needs to be said,
>> without a comment (but you need to have written a trustworthy macro or
>> subroutine at some point.  Some people would claim that this goes too
>> far.)

>> c = pak.iphdr.saddr & 192;   /* mask upper bits to get network class
>> */ netclass = pak.iphdr.saddr & 0xC0;  /* get network class */
>> netclass = GET_NETWORK_CLASS(pak);

Yes. An excellent example of going too far :-).
There is (arguably) nothing wrong with what version 3 does, as long as
the writer is aware of what is and isn't being done, and doesn't mind
the information loss inherent in this method, and does it all on
purpose.

A danger, as Olin notes, (in his own inimitable style :-) ) , is that
information may be lost inadvertently

> This is yet another example of the fallacy of "self documenting" code.  The
> author thinks everything is obvious, so doesn't bother to explain it
> further.

Yes. But more than that.
The line IS far more readable "at a glance" for the purposes of
conveying the primary function. But, what it does in the process is
hide information which may be valuable either generally, or in some
cases as part of troubleshooting or understanding some behaviour. The
fine detail still has to be provided and dealt with somewhere (which
bits, which mask etc) and, as the detail is hidden here, it needs to
be explicitly revealed somewhere else. In the case of a macro the
"revealing" will be done in the listing following the macro, if this
level of detail is enabled, and in the case of a function call or
subroutine the "detail", if required to be known, may need to be
extracted with extra user effort. The extraction is liable to be far
more difficult than 'just reading it from the code line' as is
possible in the first version.

So, what we have in version 3 is "self documentation" which targets a
particular facet of the code, which will often be the main one when
things are going right, and hides "lower level detail" which will
often be less important, when things are going right.

A major problem is that, when examining code that somebody else has
written, you usually feel the need to wade through code at this level
when things are NOT going right. At that stage the specific bit mask,
specific port (known here) or means of deriving the port, specific
operator (AND/OR/XOR/...) etc are usually of interest. The use of self
documentation as done here means it takes more effort to determine
these things.

> Big mistake, and bad programming.

Perhaps "different" than bad.
A choice has been made to be "dumber", to offer less information and
to hide "usually irrelevant" information.

This level of hiding is inherent in HLLs and is partially due to the
code being made to appear HLL like. Note that Vitaliy's original
comments were intended to be applied only to HLLs (if you can call C
an HLL :-) ).

________

> No matter what information you think a bare line of code conveys (and keep
> in mind it very rarely conveys as much as you think at the time), that
> information has to end somewhere.  Wherever that is, the comment is a great
> place to illuminate the next level up of information.

Yes. This applies at all levels of code. There are always things that
MAY be useful to know that the code can't or wasn't designed to
convey. No self documenting code system (except perhaps one written in
COBOL ( :-) ! )  would attempt to convey everything that might be
useful to be known about a given line or block of code. Some writers
may make a point of minimising the extra information that is provided
(and Vitaliys 'one comment per 100 lines of C' sounds like an example
of that) but nobody can sensible deny that such external information
exists.

So, what Vitaliy seems to be asserting is that immediately relevant
information can be adequately contained within the code itself AND
THAT programmer or reader disciplines, education, mindset and practice
means that they are able to acquire and manage such extra information
mentally or by other means without the need for it to be replicated
alongside the code in the form of comments. The success or otherwise
of  "self documenting"  systems probably depends on the extent to
which such attempts at managing 'extra information' are viable.

I recently looked at some machine code that I had written and which I
have not looked at for 13 years. Application may be described as semi
real-time control with user keypad interaction. The code is extremely
heavily commented at all levels, even by Olin's standards. Starting
semi-randomly I had no difficulty picking up immediately on what was
being done and why and how. To what extent this is due to my memory of
what I wrote then or of the system - but after 13 years I'd expect
that contribution to be small.

I find it hard to imagine that a 'self documenting' system would have
allowed me to pick up the thread again without extensive establishing
of context from elsewhere in the code. I may be wrong :-).




                     Russell

2010\06\21@064100 by sergio masci

flavicon
face


On Sun, 20 Jun 2010, Olin Lathrop wrote:

{Quote hidden}

Yes I agree, in the state it was in it could probably have done with a
comment. However you would have probably spent less time guessing if I had
formally defined a convention for the macro names I used rather than just
presenting them (as I did). This would normally be something that would
evolve to fulfill the needs of the code being developed (no point defining
a convention that includes 64 bit floating point variables if the system
doesn't need to use them).

Also, one of the things I am trying to highlight is that the code should
be MADE EASIER TO FOLLOW and the reader should be engouraged to ACTUALLY
READ THE CODE and have the comments indicate where there are obscure
things happening. I'm pretty sure I achived that otherwise I can't see you
of all people wasting time working through something that was an
uncommented mess :-)

Friendly Regards
Sergio Masci

2010\06\21@064657 by sergio masci

flavicon
face


On Sun, 20 Jun 2010, William "Chops" Westfield wrote:

{Quote hidden}

Yes but it's not only the fact that you've removed the comment that is
important - you've also attached meaning to that fraction of code (not
only for yourself or another person BUT ALSO FOR THE COMPILER).

Say while you are defining GET_NETWORK_CLASS you think to yourself "there
really should be a coressponding SET_NETWORK_CLASS" so you define it as
well. GET_NETWORK_CLASS and SET_NETWORK_CLASS now have a relationship and
this makes it easier for you to maintain both when you make changes to
either. They don't need to be macros they could be proper functions.
The relationship could be something as simple as a convention you've
invented (e.g. for every GET_xxx there needs to be a SET_xxx).

If you only had line types (1) or (2) in your code you would need to hunt
through your code for anywhere that might "set up the network class" when
you change the code that "gets the network class". You might have to rely
on searching through comments but there is nothing that guarentees the
correctness or even the existance of a comment you could home in on!

trying to make something that trips the compiler or assembler when you
make a BAD change is key (you simply can't do this with comments).

Say you did something like

       a = FUNC(b, c)

and you did this all over your code. Now for some reason you need to
change *SOME* of these to

       b = FUNC_B(a, c)

How would you ensure that you checked each one? How would you give 100%
guarentee that you've done all the work correctly (let's say a life
depends on it)? Personnaly I would change the name of FUNC to FUNC_A then
as I went through and checked each use of FUNC I would change the use from
FUNC to either FUNC_A or FUNC_B. Now if the code wont compile I know there
is a problem.

Ok, what has this to do with GET_NETWORK_CLASS you ask. Well in the same
way that you can get the compiler to trip when you rename FUNC to FUNC_A,
you can get the compiler to trip when you change GET_NETWORK_CLASS to
GET_NETWORK_CLASS_x. You can't do this with COMMENTS! Of course, once
you've finished playing about with GET_NETWORK_CLASS_x, you can simply
rename it back to GET_NETWORK_CLASS.

Ok so how to you ensure that SET_NETWORK_CLASS gets updated when
GET_NETWORK_CLASS is modified? You either need something shared by both so
that changing GET_NETWORK_CLASS and the shared item causes the compiler to
trip while it's working through SET_NETWORK_CLASS (maybe a
NETWORK_CLASS_FUNC_NEEDS_CHANGING macro which gets changed to
NETWORK_CLASS_FUNC_NEEDS_CHANGING_X) or you need to rely on a comment. I
didn't say you can't use comments just that you are trying to greatly
reduce your dependence on them and only put them in where they are
necessary.

Regards
Sergio Masci

2010\06\21@070748 by RussellMc

face picon face
> Yes but it's not only the fact that you've removed the comment that is
> important - you've also attached meaning to that fraction of code (not
> only for yourself or another person BUT ALSO FOR THE COMPILER).
...

All good stuff.
But a reasonable amount of that can be achieved by use of more
meaningful names in assembler.
There's no rule against meaningful names AND comments as well :-).

Gains can also be had from multiple naming (Danger! Will Robinson)
variables. The latter either in parallel or series.
A <--B, A <--C   versus  A <-- B <-- C. In part this depends on
whether your tool allows this.
This of course also opens up grand opportunities to destroy yourself
if you wish to allow them.
A certain amount of discipline and systems approach is needed to do
such things - but anyone who programs in assembler without such is
probably headed for disaster anyway :-). (Disciplines can be enforced
'programmatically)(lint for assembler?) or manually. The latter
probably only for high wire without a net types.



         Russell

2010\06\21@072055 by Olin Lathrop

face picon face
RussellMc wrote:
> The line IS far more readable "at a glance" for the purposes of
> conveying the primary function. But, what it does in the process is
> hide information which may be valuable either generally, or in some
> cases as part of troubleshooting or understanding some behaviour. The
> fine detail still has to be provided and dealt with somewhere (which
> bits, which mask etc) and, as the detail is hidden here, it needs to
> be explicitly revealed somewhere else. In the case of a macro the
> "revealing" will be done in the listing following the macro, if this
> level of detail is enabled, and in the case of a function call or
> subroutine the "detail", if required to be known, may need to be
> extracted with extra user effort. The extraction is liable to be far
> more difficult than 'just reading it from the code line' as is
> possible in the first version.

Good point, I hadn't thought of it quite that way before.  This way of
thinking argues clearly for the second of the two examples instead of the
third.  If you look at it this way, the second is really a superset of the
third.  It shows the details in the code so someone who needs the details
doesn't have to go chasing after a macro definition, but it also gives you
the same higher level information in the comments that the third line does
in the code:

>>> c = pak.iphdr.saddr & 192; //mask upper bits to get network class
>>> netclass = pak.iphdr.saddr & 0xC0; //get network class
>>> netclass = GET_NETWORK_CLASS(pak);

The winner might not be so clear if GET_NETWORK_CLASS expanded to a more
complicated function or the third line had a comment indicating the next
higher up information, like why we need the network class.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2010\06\21@073426 by sergio masci

flavicon
face


On Mon, 21 Jun 2010, RussellMc wrote:

> > Yes but it's not only the fact that you've removed the comment that is
> > important - you've also attached meaning to that fraction of code (not
> > only for yourself or another person BUT ALSO FOR THE COMPILER).
> ...
>
> All good stuff.
> But a reasonable amount of that can be achieved by use of more
> meaningful names in assembler.
> There's no rule against meaningful names AND comments as well :-).

I'm NOT saying not to use these. What I am saying is that comments don't
help the compiler or assembler or any other development tool that I know
of. Moving the information from the comment to a more "tool" readable /
actionable representation ultimately helps the developer.

>
> Gains can also be had from multiple naming (Danger! Will Robinson)
> variables. The latter either in parallel or series.
> A <--B, A <--C   versus  A <-- B <-- C. In part this depends on
> whether your tool allows this.

lol, actually XCASM lets you do stuff like that, it helps compiler
writing :-)

e.g.
       a0        .ds        1
       a1        .ds        1
       b        .alias        .word a0

               .let        b = b+1 ; emit executable code that
                               ; increments a0:a1 as a 16 bit word

Regards
Sergio Masci

2010\06\21@141818 by Vitaliy

face
flavicon
face
Marechiare wrote:
< He seems to be saying that if you name your variables
> correctly (or perhaps do some other clever thing that I'm
> unable to ascertain) then one needs only write, typically,
> one comment per 100 lines of HLL code.

-->His point, as I see it, is - do not over-stuff you Chinese code with
English comments. Better try learning how to express things in Chinese
clearly and concisely (not necessarily on a native level), after you
mastered the style, you, probably, won't need adding English comments
at all :-) <---


I would have to find the post with the original comment later, but that is
totaly not what I'm saying.

In a nutshell, a lot of the things that people say in comments, can be
eliminated by making the code more readable. This includes structuring the
code so it's easier to follow and properly naming variables and functions.
It sounds more difficult than it really is, after a while it becomes second
nature.

Vitaliy

2010\06\21@170846 by Wouter van Ooijen

face picon face
> In a nutshell, a lot of the things that people say in comments, can be
> eliminated by making the code more readable. This includes structuring the
> code so it's easier to follow and properly naming variables and functions.
> It sounds more difficult than it really is, after a while it becomes second
> nature.

And after doing the above, which I definitely don't object to, the
author can (and should!) write some comments that explain what is still
not in the code.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2010\06\21@171128 by Marechiare

picon face
> -->His point, as I see it, is - do not over-stuff you Chinese code with
> English comments. Better try learning how to express things in Chinese
> clearly and concisely (not necessarily on a native level), after you
> mastered the style, you, probably, won't need adding English comments
> at all :-) <---
>
>
> I would have to find the post with the original comment later, but that is
> totaly not what I'm saying.
>
> In a nutshell, a lot of the things that people say in comments, can be
> eliminated by making the code more readable. This includes structuring the
> code so it's easier to follow and properly naming variables and functions.
> It sounds more difficult than it really is, after a while it becomes second
> nature.

That was an analogy. The language of code was called Chinese (no
offense to Chinese people meant) and comments were "English comments".

" learning how to express things in Chinese clearly and concisely "
was an analogy to "This includes structuring the code so it's easier
to follow and properly naming variables and functions"

2010\06\21@222641 by RussellMc

face picon face
Thought this sent yesterday - now covered partly by what Wouter said.

> > > Yes but it's not only the fact that you've removed the comment that is
> > > important - you've also attached meaning to that fraction of code (not
> > > only for yourself or another person BUT ALSO FOR THE COMPILER).

> > All good stuff.
> > But a reasonable amount of that can be achieved by use of more
> > meaningful names in assembler.
> > There's no rule against meaningful names AND comments as well :-).

> I'm NOT saying not to use these. What I am saying is that comments don't
> help the compiler or assembler or any other development tool that I know
> of. Moving the information from the comment to a more "tool" readable /
> actionable representation ultimately helps the developer.

And I'm not saying that you shouldn't move "comments" into the code to
the extent reasonably possible. But I note that it can become
increasingly cumbersme to do so and a pint is reached where you have
things to say ABOUT the line of code which are not direct functions of
the code, so cannot be meaningfully included in it.

That may e a good guide to self documenting capability. Something like:

"To the maximum extent reasonably possible, information about the
functionality of a line of code which is  contained in a comment line
should instead be moved into the code."

and

"Coding nomenclature should reflect code functionality to the maximum
extent reasonably  possible."


   Russell



{Quote hidden}

>

More... (looser matching)
- Last day of these posts
- In 2010 , 2011 only
- Today
- New search...