Searching \ for '[OT] Re: How to write bad code - was Re: C vs. ASM' 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/language/index.htm?key=asm
Search entire site for: 'Re: How to write bad code - was Re: C vs. ASM'.

Exact match. Not showing close matches.
PICList Thread
'[OT] Re: How to write bad code - was Re: C vs. ASM'
1999\11\17@012548 by w. v. ooijen / f. hanneman

picon face
Today I read a list of guidelines someone wrote
for coding (for C, but that does not matter).
There was one line that struck me because it
is not often seen in such lists but I think it is
totally correct:

- comments should be avoided unless necessary to
explain the purpose or working of the code

Of course one can debate about when a comment
is necessarry, but I still think this is a good guide.
One of the rationales behind this guideline is that
code + comment form a "same info in two locations"
pair, which should generally be avoided because
such pairs always tend to get out of sync.
Note that the guideline can also be read as encouraging
to write code that does not need commenting.

Wouter

1999\11\17@090848 by Wagner Lipnharski

picon face
"w. v. ooijen / f. hanneman" wrote:
>
> Today I read a list of guidelines someone wrote
> for coding (for C, but that does not matter).
> There was one line that struck me because it
> is not often seen in such lists but I think it is
> totally correct:
>
> - comments should be avoided unless necessary to
> explain the purpose or working of the code

Of course you should not comment the formula steps:

18) Pour 100g of NaCl into the mix.
19) Do not steer.

if you have a previous explanation about what the heck those steps are
for.. are they need to increase brix? gives a salty taste? removes
accidity taste? change mix color? generate other solids decay? just for
the fun of it? ruin your sister soup?  Without any explanation, you will
never be able to change the formula as you wish, because the use of the
NaCl is not clear.

1999\11\18@010149 by Russell McMahon

picon face
From: w. v. ooijen / f. hanneman <spam_OUTwfTakeThisOuTspamXS4ALL.NL>

>Today I read a list of guidelines someone wrote ..
>- comments should be avoided unless necessary to
>explain the purpose or working of the code


I agree absolutely.
Unnecessary comments get in the wy
BUT

>Of course one can debate about when a comment
>is necessarry, but I still think this is a good guide.
>One of the rationales behind this guideline is that
>code + comment form a "same info in two locations"
>pair, which should generally be avoided because
>such pairs always tend to get out of sync.
>Note that the guideline can also be read as encouraging
>to write code that does not need commenting.


OK.
Lets think of when comments aren't necessary -

- Code intention is clear at a glance to you now, to you 2 years from now
and anyone else who may have to read the code at ANY future date.

- No inobvious tricks have been carried out whatsoever ie at a minimum, you
aren't using C or assembler, you are probably using Pascal or ... :-)

- The purpose of the routine doesn't need to be known or is completely
obvious.

- Data used, data modified, parameters passed, stack usage, critical timing
issues, dependence on other code, use of other code, functionality and
anything else you can think of are either non-existent or completely
unimportant.

On a line by line basis:

-     I know what the line does (eg WHY it branches, WHERE it branches, what
the conditions are for the branch, what caused them, what changes them, ...)

Consider the code snippet from the other day.
This was sort-of-randomly chosen (a new algorithm for pseudo-random
selection :-))
I'm NOT proud of this as code - it's meant to be a documentation discussion
example :-)
Which if any of this is unnecessary.
Current comments below will be in [CAPITALS AND SQUARE BRACKETS] - ie have
been added just now by me.
Comments on comments precede the line they relate to.

This code is about 50% documentation on a line count basis and much more
than 50% on a character count basis.
Yes, some comments could definitely vanish.
What would you remove?
Why?
What would be gained by doing so?

Yes, there can be some gains as mentioned by others recently.

- Time saved not writing comments.
- when I change the code the non-existent comments won't mislead people
- when I cut and paste the code the non-existent comments won't mislead
people
- etc

The 2nd and 3rd points are valid traps to avoid but I submit that a
background of comment writing will lead you to being aware of them. Mostly
anyway :-)

----------------------------------------------------------------------------


;;* Now clear PWM output
; **********************

[NEXT LINE SOMEWHAT REDUNDANT BUT DIFFERS FROM ABOVE]

;;* PWM trigger point has been reached. Now set output low.


[NICE TO HAVE PHILOSOPHY OF YOU EVER WANT TO MAKE CHANGES OR WONDER WHY
KIT'S DONE THIS WAY]
; Technically this action is unneeded in STOP mode but it is an added safety
feature
; to ensure PWM is off (provided that SHADOWB/KPWMOUT is low, as it should
be, having
; been cleared a few lines back.) This also allows beeper resetting and
anything else
; that is using the port. When Beeper-AC is running it will update the port
frequently.

[COULD HAVE SUS'D THIS FROM CODE - I THINK COMMENT IS STILL OK]
       BCF     ShadowB, KPWMOUT ; set shadow PWM bit low.
[A BIT REDUNDANT]
       MOVF    ShadowB, W      ; get shadow port (with PWM bit set low
already)
[VERY REDUNDANT - BUT UNNECESSARY?]
       MOVWF PORTB  ; output it

[BLOCK COMMENT ONLY. NO COMMENT ON 2=3 INDIVIDUAL LINES. CLEAR ENOUGH TO DO
THIS ]

; Now for assessment (again) of where the non-critical code should run.

       BTFSS   FLAGS, FSpareTime
       GOTO    LoNonCrit
       GOTO    SkipLoNC

[SIMILAR]
LoNonCrit       ; Start of once per cycle non time critical code
                       ; which should be run

[LABEL ALMOST "DOCUMENTATION"]
       CALL    DoNonCrit

SkipLoNC


[SHOULD THIS EXPLANATION BE EXCLUDED?]
[IF SO, WHY?]

;;* WAIT FOR END OF PWM CYCLE:
; ****************************

;;* Now we can set and wait until the timer cycle finishes.
;;* At 100% duty cycle this will be immediate.
;;* Endpoint occurs when timer2 (PBF5.2) reaches the max allowed PWM value.

WAIT4END:   ; Loop to here until PWM output ready to be set to off.

[OK. YOU CAN TAKE THIS COMMENT OUT :-)]
       CLRWDT           ; Clear watchdog timer

[AND SO ON ...]
       MOVLW KPWMMAX  ; Get maximum timer value
                       ; PBF5.2:         SUBWF   TIMER, W        ; See if
yet up to max value
       SUBWF   TIMER2, W        ; See if yet up to max value

;; debug PBF4A2 - replace with carry bit check -  BTFSS   STATUS, ZERO    ;
B if trigger point reached,

       BTFSS   STATUS, CARRY   ; Finish when Timer-Tmax goes positive.
      GOTO WAIT4END ; , else loop again

;;* PWM is low, we are at the end of the cycle. Go back and start again.

;;* All done - go round power.

GOTO  LOOPIT

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


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

1999\11\18@022302 by Richard Martin

picon face
A very bright programer once worked for me who felt that
"unnecessary <newlines> (CR/LF) and spaces got in the way (in 'C')"
and further "longwinded names also got in the way" < started
at 'a', 'b'......'z' then went to 'aa', 'ab'...'az' etc.>.

I hope his next employer found it as entertaining and 'paper
saving' as I did.

R.Martin

Russell McMahon wrote:

> >Today I read a list of guidelines someone wrote ..
>
> I agree absolutely.
> Unnecessary comments get in the wy
> BUT

1999\11\18@023544 by William Chops Westfield

face picon face
Surprisingly, one of the times that it is common NOT to comment very
verbosely is when the algorithm used is in fact VERY complex.  In this
case it's generally assumed that the code is documented extensively
EXTERNALLY (like, in books, papers, patents, and so on.)  For example,
I've never seen anyone attempt to extensively comment a routine that
calculates CRCs (either bitwise or bytewise.)  Your program is NOT
the place to explain why a series of shifts and xors ends up producing
coefficients for a polynomial...

BillW

1999\11\18@092940 by Wagner Lipnharski

picon face
William Chops Westfield wrote:
>
> Surprisingly, one of the times that it is common NOT to comment very
> verbosely is when the algorithm used is in fact VERY complex.  In this
> case it's generally assumed that the code is documented extensively
> EXTERNALLY (like, in books, papers, patents, and so on.)  For example,
> I've never seen anyone attempt to extensively comment a routine that
> calculates CRCs (either bitwise or bytewise.)  Your program is NOT
> the place to explain why a series of shifts and xors ends up producing
> coefficients for a polynomial...
>
> BillW

Yes, No, and probably "Maybe"... hehe

At IBM we use to debug software with 600+ pages x 66 lines / page. All
the documentation was listed together with the code, just because the
code was regenerated twice a day... it would be impossible to keep an
external reference to what each small routine was doing.

Recently I finished a 16,000+ lines of code, I created a external text
file just for comments.  The code needed to be generated in 3 files,
using "include" function, because the DOS text editor couldn't stand a
650k file size... <g>... even so, it was a pain in the neck to keep
commenting in one file and changing code in another file.   I would love
to see a code editor that could do both functions at once...

I already have lots of troubles to keep track of what version is the
last one, with so many protection copies, backups, moving disks from one
computer to another and so on.  I am *not* that organized.  It was the
version I changed code in the office, or at the lab?, or the one I did
at my home last night? I changed it last night? or it was something
else?... arggg, too old!  brain is starting to fail.

The CRC routine is very simple, few lines of commented code do it
nicely, but try to do the same for a HDLC (IrDa) communication routine,
the commenting details take more space than the code itself, but it is a
must to be able to understand it latter.

Wagner.

1999\11\18@104310 by Don Hyde

flavicon
face
A reference to a standard textbook or patent disclosure takes very little
space in the source code.

> {Original Message removed}

1999\11\18@104504 by Dave VanHorn

flavicon
face
> A very bright programer once worked for me who felt that
> "unnecessary <newlines> (CR/LF) and spaces got in the way (in 'C')"
> and further "longwinded names also got in the way" < started
> at 'a', 'b'......'z' then went to 'aa', 'ab'...'az' etc.>.


Then you have the guys who code that way in HTML:

New_Page_Boundary_Exception_Flag_Set_bit

and wonder why their web pages take half an hour to load.

1999\11\18@114054 by eplus1

flavicon
face
I'd like to suggest a link to one of the more stable online sites for
programming algorithms or to the programmers own site as a way of
documenting this sort of thing. Maybe just a link to a http://www.yahoo.com
search for the name of the algorithm or to the foldocs site
http://wombat.doc.ic.ac.uk/foldoc/index.html.

For example: for crc's:
ink.yahoo.com/bin/query?p=crc+algorithm&hc=0&hs=0
or
http://wombat.doc.ic.ac.uk/foldoc/foldoc.cgi?query=crc&action=Search

even if the links change (yahoo goes bust etc...) the fact that a general
search was linked should clue the future reader that this is a common
algorithm

James Newton .....jamesnewtonKILLspamspam@spam@geocities.com phone:1-619-652-0593
http://techref.homepage.com NOW OPEN (R/O) TO NON-MEMBERS!
Members can add private/public comments/pages ($0 TANSTAAFL web hosting)
PIC/PICList FAQ: http://204.210.50.240/techref/default.asp?url=piclist.htm


{Original Message removed}

1999\11\18@161352 by paulb

flavicon
face
Richard Martin wrote:

> A very bright programer once worked for me who felt that
> "unnecessary <newlines> (CR/LF) and spaces got in the way (in 'C')"

 I gather you are referring to the habit of putting multiple
expressions per line.

 What does make code *very* unreadable however is the practice of
double-spacing.  A single blank line between functional blocks doesn't
hurt (In assembler, a blank line after a "GOTO" or "BRA", except in PIC
code where GOTOs follow skips of course in which case indentation is
elegant), but gobs of whitespace ("adipose tissue"!) really make it
difficult, if only because you are less likely to fit essentially
connected sections of code on the one page/ screen.
--
 Cheers,
       Paul B.

1999\11\18@170403 by Mike M

flavicon
face
I dont understand the big deal that people have with comments and blank lines???
who cares really. if u have to turn in your program to someone yes it would be
nice if u made it look neat and indent and comment lines etc.  if your coding fo
r yourself and no ones ever gonna see it anyway who cares.  If your coding and s
omeone wants help and u send them a sample of your code so they get the idea and
there are no comments in there...its their problem.  Lets face it comments and
"prettyness" are unnecissary, they are not included in the final package they ar
e mearly a convience when re-reading some of your old stuff so you or those u wo
rk with know whats going on quickly and easily.

MikE
PS.. I never comment, because if anyone gets my code...i hope they do get confus
ed : )  j/k hehe



On Fri, 19 Nov 1999 08:12:48 +1100 "Paul B. Webster VK2BZC" <paulbspamKILLspamMIDCOAST.COM.
AU> wrote:
{Quote hidden}

Send someone a cool Dynamitemail flashcard greeting!! And get rewarded.
GO AHEAD! http://cards.dynamitemail.com/index.php3?rid=fc-41

1999\11\18@171425 by Quitt, Walter

flavicon
face
You describe what is refered to as programming in the small.
In the small, "who cares" is OK.  You are they only one
messing with it.

When you get to bigger things with multiple programmers
and lots of modules (as I am doing with a 17C756 and,
now, 87% of the program memory used) it makes a BIG
difference!  Coding style, comments, indenting have
saved our butts lotsa times now.  Our design docs
have allowed us to make changes we never thought
we could.  Uncommented code is like a run on sentance;
who knows what it really means?

Been doing embedded work since the 8080 and such practices
have saved me many many times.  If the code works, then
great.  If it is broken or you have to modify it in
a few months, good luck without good comments.  I hate
to have to refigger out what I did.  It is a waste
of time not to (meaningufully) comment.

Flame off,
Walt...


{Original Message removed}

1999\11\18@180436 by Dave VanHorn

flavicon
face
> MikE
> PS.. I never comment, because if anyone gets my code...i hope they do get
confused : )  j/k hehe


I'll remember that when your resume hits my desk. :)

1999\11\18@182108 by Nick Taylor

picon face
Yur rite MikE ... its kinda like spellin ... as long as it werks its ok!
- Nick -

Mike M wrote:
>
> I dont understand the big deal that people have with comments and blank lines?
?? who cares > really. if u have to turn in your program to someone yes it would
be nice if u made it look neat > and indent and comment lines etc.  if your cod
ing for yourself and no ones ever gonna see it > anyway who cares.  If your codi
ng and someone wants help and u send them a sample of your code so > they get th
e idea and there are no comments in there...its their problem.  Lets face it com
ments > and "prettyness" are unnecissary, they are not included in the final pac
kage they are mearly a > convience when re-reading some of your old stuff so you
or those u work with know whats going on > quickly and easily.
>
> MikE
> PS.. I never comment, because if anyone gets my code...i hope they do get conf
used : )  j/k hehe
>
> On Fri, 19 Nov 1999 08:12:48 +1100 "Paul B. Webster VK2BZC" <.....paulbKILLspamspam.....MIDCOAST.CO
M.AU> wrote:
{Quote hidden}

1999\11\18@183103 by Mike M

flavicon
face
Actually i have to agree with Walter...Like i said, if your working with people
of course i dont see how you can go without the comments, however writing code o
n your own or working on a project alone where no one else needs see or know how
it works AS LONG AS IT WORKS..thats the point isnt it working code : )

MikE
PS. to Dave, no one will be getting my resume ;)

On Thu, 18 Nov 1999 14:13:34 -0800 "Quitt, Walter" <EraseMEwquittspam_OUTspamTakeThisOuTMICROJOIN.COM> wrote:
{Quote hidden}

>{Original Message removed}

1999\11\18@185009 by Mark Willis

flavicon
face
Wagner Lipnharski wrote:
> <snipped>
> I already have lots of troubles to keep track of what version is the
> last one, with so many protection copies, backups, moving disks from one
> computer to another and so on.  I am *not* that organized.  It was the
> version I changed code in the office, or at the lab?, or the one I did
> at my home last night? I changed it last night? or it was something
> else?... arggg, too old!  brain is starting to fail.
> <snipped>
> Wagner.

How I handle source backups, in a Batch file;  I run this once per
BOOTUP, usually - yeah, eats space - but it means I have CURRENT
backups, always.  I do the same with other critical files.  Inline'd
some called subroutines.  Yeah, no comments, so shoot me <G>  (And I
usually put each project's name in place of the "Backup" part of the zip
files below, this is "genericized" somewhat.)  Keep meaning to write a
Pascal or C program to handle doing this with more "uniqueness" (i.e.
don't end up with 7 copies of the same version), but haven't.

{Quote hidden}

Another rule I've learned is, "There CAN BE only ONE master copy of
source code."  So - my master copy gets put on a laptop while in work,
and STAYS on there, all other copies are slave copies, if I'm likely to
work on it anywhere but at the development machine.  PC110's are GREAT
for this, work well for text editing for me <G>

 Mark

--
I do small package shipping for small businesses, world-wide.

1999\11\18@205634 by Russell McMahon

picon face
>I dont understand the big deal that people have with comments and blank
lines??? who cares really. if u have to turn in your program to someone yes
it would be nice if u made it look neat and indent and comment lines etc.
if your coding for yourself and no ones ever gonna see it anyway who cares.
If your coding and someone wants help and u send them a sample of your code
so they get the idea and there are no comments in there...its their problem.
Lets face it comments and "prettyness" are unnecissary, they are not
included in the final package they are mearly a convience when re-reading
some of your old stuff so you or those u work with know whats going on
quickly and easily.
>
>MikE




I sat awhile trying to decide whether this was "tongue in cheek" or serious.
I guess it's intended seriously.
If so, expect an interesting life in years to come :-)


RM

1999\11\18@212129 by Wagner Lipnharski

picon face
> I sat awhile trying to decide whether this was "tongue in cheek" or serious.
> I guess it's intended seriously.
> If so, expect an interesting life in years to come :-)
>
> RM

hehe Russell, I would say it differently:
There is an ancient chinese proverb that says:
The one that sweep dust below the carpet is primarily a "dust collector"
with a big carpet.

1999\11\19@014455 by Russell McMahon

picon face
From: Mike M <elektrikmanspamspam_OUTDYNAMITEMAIL.COM>

>Actually i have to agree with Walter...Like i said, if your working with
people of course i dont see how you can go without the comments, however
writing code on your own or working on a project alone where no one else
needs see or know how it works AS LONG AS IT WORKS..thats the point isnt it
working code : )


Yes, as long as it works IS the measure.
What "works" means is the skill.

"Works" here may imply

- OK it runs now, don't know what I did to make it work but it's OK now so I
won't touch it again.
- OK, I remember what that did when I wrote it 1 minute / 1 hour / day / 1
week / 1 month / 1 .... ago so I can change this here and know just what the
result will be.
- I'm happy to decode the whole thread of this code if I ever have to look
at it again so that's OK.
- I'm a genius with a photographic memory so there's never a problem.

For most people none of these apply.
#4 is obviously vanishingly  rare.
#3 is acceptable to about 0% of  bosses who have to pay for your resource.
#2 is about 1 hour to 1 week for me :-), about 1 minute for some and
probably not more than 1 month for almost anyone expect the guy (or gal) in
#4.

Unless you write code once and for ever its unlikely that you can survive on
zero comments (if then).

RM

1999\11\19@090654 by Mike M

flavicon
face
welp guess i got a photographic memory.  Ive been programming since i was 12, li
ke i said IF YOU ARE WORKING THEN ITS A DIFFERENT STORY..everyone is one my case
because they assume i do not comment when i am at work.  Work you are developin
g usually with more then a few people, obviosuly the entire project would take t
ripple (maybe more) then time to do if each person had to "untangle" the code fr
om the person before him.  However, IF YOU ARE CODING FOR YOURSELF THEN IT REALL
Y DOESNT MATTER, A YEAR FROM NOW WHEN U HAVE NO IDEA WHAT THE CODE MEANS THEN IT
S YOUR PROBLEM AM I RIGHT?

For big projects, working with other, or when there will be more then one or 2 p
ages of code i put comments, other then that i can look at a page of code, (espe
cially VB code) and know what it does in less then a couple of minutes, maybe it
s just me.

In my teams current project we are building a stamp clone for personal use, alon
g with our own PBASIC type programming lanugage and compiler/interpretur (? i ca
n never spell that word right,o well its the internet).  So far for the compiler
alone there is 20 pages of code, and YES THERE IS COMMENTS, im sorry that i jus
t jot these letters out real fast while at work, and now that i read my old mess
ages and new replies i have even confused myself.

Mike

On Fri, 19 Nov 1999 15:07:29 +1300 Russell McMahon <@spam@apptechKILLspamspamCLEAR.NET.NZ> wrote:
{Quote hidden}

Send someone a cool Dynamitemail flashcard greeting!! And get rewarded.
GO AHEAD! http://cards.dynamitemail.com/index.php3?rid=fc-41

1999\11\19@093233 by Nick Taylor

picon face
Mike,

Are you putting us on?

- Nick -

Mike M wrote:
>
> welp guess i got a photographic memory.  Ive been programming since i was 12,
like i said IF YOU ARE WORKING THEN ITS A DIFFERENT STORY..everyone is one my ca
se because they assume i do not comment when i am at work.  Work you are develop
ing usually with more then a few people, obviosuly the entire project would take
tripple (maybe more) then time to do if each person had to "untangle" the code
from the person before him.  However, IF YOU ARE CODING FOR YOURSELF THEN IT REA
LLY DOESNT MATTER, A YEAR FROM NOW WHEN U HAVE NO IDEA WHAT THE CODE MEANS THEN
ITS YOUR PROBLEM AM I RIGHT?
>
> For big projects, working with other, or when there will be more then one or 2
pages of code i put comments, other then that i can look at a page of code, (es
pecially VB code) and know what it does in less then a couple of minutes, maybe
its just me.
>
> In my teams current project we are building a stamp clone for personal use, al
ong with our own PBASIC type programming lanugage and compiler/interpretur (? i
can never spell that word right,o well its the internet).  So far for the compil
er alone there is 20 pages of code, and YES THERE IS COMMENTS, im sorry that i j
ust jot these letters out real fast while at work, and now that i read my old me
ssages and new replies i have even confused myself.
>
> Mike
>
> On Fri, 19 Nov 1999 15:07:29 +1300 Russell McMahon <RemoveMEapptechTakeThisOuTspamCLEAR.NET.NZ> wrot
e:
{Quote hidden}

1999\11\19@100704 by Tracy Smith

picon face
--- Mike M <TakeThisOuTelektrikmanEraseMEspamspam_OUTDYNAMITEMAIL.COM> wrote:
> welp guess i got a photographic memory.  Ive been
> programming since i was 12, like i said IF YOU ARE
> WORKING THEN ITS A DIFFERENT STORY..everyone is one

Does that mean you have 5 years of experience now? If
you could write code as complicated as some of the
members on this list you'd see how important comments
really are. Without comments, absolutely no one can
possibly understand what I write. Without comments, I
often have a hard time understanding what I write. I
re-use the same tricks over and over, but the context
in which they're used is extremely important.

BTW, for your basic clone thingy, read up on interrupt
programming and isochronous coding techniques - these
two subjects alone would go a long way to help you
implement a "background" servo controller. While
you're at it, you may wish to study state machines.

Sorry for being so harsh, but I really don't believe
you know what you're saying.

.lo
__________________________________________________
Do You Yahoo!?
Bid and sell for free at http://auctions.yahoo.com

1999\11\19@120922 by Mike M

flavicon
face
>Does that mean you have 5 years of experience now? If
>you could write code as complicated

No and lets not turn this into some kind of flame war im 22, still in school maj
oring in electronics engineering tech. I have majored in software engineering bu
t changed my major after 2yrs.

The point is as i have been saying for the past 5 emails is that everyone compla
inig about comments..and i say it depends on the situation.  I dont know how thi
s turned into a whole..abuse mike.. scenario.  Again i will say it, you writing
your code that is so complicated etc. you putting comments is up to you unless y
ou are working with a team because then no one will have any idea what you are d
oing unless they sit an analyze it.  If i am writing a program for myself who ca
res if i am putting comments or not?  Why should anyone care..its like im tellin
g you your an idiot for adding comments..im just saying that i personally do not
comment unless i know its either a group project or my code is very long and co
mplicated as you said.  True  i know very little about pic mcu's but enough of t
he 68hc11 to get what i need done; 68hc11 is much easier to use, just not cost e
ffective in most cases.

 So now how did this turn to a big argument that i suddenly dont know anything
about programming?



On Fri, 19 Nov 1999 07:06:02 -0800 Tracy Smith <RemoveMEdot_lospamTakeThisOuTYAHOO.COM> wrote:
{Quote hidden}

Send someone a cool Dynamitemail flashcard greeting!! And get rewarded.
GO AHEAD! http://cards.dynamitemail.com/index.php3?rid=fc-41

1999\11\19@124034 by eplus1

flavicon
face
I think you are right... if the code is for you only, or for a one-time only
problem and its not complex why waste time? But earlier you seemed to be
saying that commenting is never worth it. That point is arguable.

I will have to admit that I know of a company that only cares about getting
the current program out the door ASAP and really has no intention of
supporting it or modifying it in the future. They know that the next version
will be in a different development language, different environment, have
enough new features that it is better to just trash the old code and start
over. When the program is first tested and released, the programmer(s) are
involved enough in the code to be able to quickly fix any major bugs and
after about 3 months, they are on to the next project and will never go back
and update that code. They have even, on occasion, lost the source and
haven't really gotten upset about it. What good is documentation in that
company?

One thing that they do, is to document what tricks they learned related to
the project that have nothing to do with the programming language etc... in
a separate "knowledge base" so that they will have them for the next time.

The idea of keeping track of the lessons learned was an inspiration for my
techref. The point is that while source code commenting is valuable, the
real gems are the bits of information that allowed you to write the program
/ design the circuit / solve the problem in the first place and buried in
the middle of the source is not the right place for these.

It brings me back to my comment about URL links to algorithm descriptions in
source code. The higher level recognition of what the code is trying to do
is more valuable in most cases than the individual commenting of lines.

James Newton EraseMEjamesnewtonspamgeocities.com phone:1-619-652-0593
http://techref.homepage.com NOW OPEN (R/O) TO NON-MEMBERS!
Members can add private/public comments/pages ($0 TANSTAAFL web hosting)
PIC/PICList FAQ: http://204.210.50.240/techref/default.asp?url=piclist.htm


{Original Message removed}

1999\11\19@125317 by Wagner Lipnharski

picon face
Mike M wrote:
[snip]
If i am writing a program for myself who cares if i am putting comments
or not?  Why should anyone care..
[snip]

I am sorry to put more logs into this fire, and probably I should not,
but, the only person that should care about this is only you. It is your
own future, and nobody should say anything or interfere how you should
have your work done, people can only suggest what is the most "common"
way to do things.

I personally don't care so much about the technique used to slice an
apple before I eat it, but if I will need to slice 10 thousand apples,
than it is better to think twice and document it before I (or other
people) start to chop things around.

I also would be very interested to see how a 18 thousand lines code can
be done without a single comment line, even if the code is for myself
and nobody else would see it.  If you think about bit, 18 thousand line
code takes at least 3 months of full day typing, and probably 2 new
keyboards, so how in the heck one can remember what means that
intrincated 600 lines algorithm he made 70 days ago, without any hint
comment?

I can see that a very little program done in a dozen C lines can
probably be more easily recognized, and if not, sometimes is easy to
rewrite it instead understand what crossed another human mind when it
was done, but, this can not be done in an average 5000 lines code.

Someone can say that commenting a source code is similar to produce an
index for a 3000 pages technical book, without it, the book is useless.

Mike, I think nobody is being rude or something like that, the problem
is that lots of folks (including me) can not understand how someone can
just remember by memory a large code strategy, or the flashes of genius
everyone have sometimes.  Everyone here probably can remember 20 or more
telephone numbers often used, but 500? 2000?

peace

Wagner.

1999\11\19@131843 by Don Hyde

flavicon
face
       [Don Hyde]  SNIP
> No and lets not turn this into some kind of flame war im 22, still in
> school majoring in electronics engineering tech. I have majored in
> software engineering but changed my major after 2yrs.
>
       [Don Hyde]  SNIP
>    So now how did this turn to a big argument that i suddenly dont know
> anything about programming?
>
       [Don Hyde]  SNIP

       Most older programmers have had the painful experience of having to
modify (under a deadline of course) un- or poorly- documented spaghetti code
written by someone else or, worse, by themselves.  That code was
undocumented for all the usual reasons -- too simple, never going to be used
again, not enough time, just written for myself, etc., or there was
documentation but it was separate from the program and got lost.

       When someone (especially one who is probably younger) tells them
they're wasting their time, they recall the pain, and cry out.  Really,
they're not stabbing at you, they're trying to save you some of the pain
they have experienced.

       So they learn to always at least take a stab at using comments to
explain the confusing parts of a program.  You never know when that code
will come back to haunt you or someone else.  This goes along with a whole
set of practices like descriptive labels and variable names that help to
reduce the confusion and misunderstanding when a human needs to read the
program.

       It's cheap for a machine to read the code and "as long as it works"
it doesn't matter how it's written, but when it stops working, a human has
to read it, and it's mongo expensive for a human to read the code.  Even if
it only helps a little, clear writing will save some pain (which is money
when you're programming for a living).

       I think it might be a good idea for would-be programmers to study
writing for humans first, then take on the easier task of writing for
machines.

       Always keep in mind that the poor bastard who's going to have to try
and figure what the !@# this code was supposed to be doing two years from
now -- has a good chance of being you.

1999\11\19@133553 by Dave VanHorn

flavicon
face
> The point is as i have been saying for the past 5 emails is that everyone
complainig about comments..and i say it depends on the situation

Mostly, my take on it is that this is a very bad habit to develop.  You will
always tend to comment less, thinking "I don't really need to..".   It's
kind of like peeing in the pool. As long as you're the only one in the pool,
then you're the only one affected.

1999\11\19@160942 by Agnes en Henk Tobbe
flavicon
face
.>if your coding for yourself and no ones ever gonna see it anyway who
cares.

Oh, Oh, you must be very new or very stupid......
You probably never had to re-read some code you wrote 5 years (or even
months) ago....
If you are new, you are forgiven. If you are stupid..... well that is your
problem.
Henk VK2GWK

1999\11\19@164230 by M. Adam Davis

flavicon
face
The only thing you are doing that we may wish to warn you against is you
are actively developing a bad habit, and, by omission, not developing a
good one.

When you finally need to start commenting code so others can work on it,
you are gong to write horrible comments, becasue you won't know the best
way to comment code and make it useful for the future (plus you'll be
rebelling against whoever asked you to write comments).  90% of the
coding I do is on someone else's code.  That person, being an engineer,
has much the same thought patterns that I do, but I dislike going
through his code and working with it.  He has a comment or two for each
procedure he has written.  I have little idea how the procedures are
used by other procedures except by going through the code line by line.
There are few variables passed between functions, choosing, instead, to
pass info with global functions; gotos scattered hither and thither; and
several other not-well-liked practices.

So, PLEASE at least start commenting for practice!  If you end up in a
position where you do no program maintenance, you will be doomed to a
life of poor commenting skills, and the maintenance programmers who deal
with your code will want to indent your code six feet downward and cover
it with dirt(1)(not to mention indenting your head (2)).

-Adam

(1) Paraphrased:
"In My Egotistical Opinion, most people's C programs should be indented
six feet downward and covered with dirt." --Blair P. Houghton

(2) Paraphrased:
A Klingon programmer's top 12 phrases:
#9 Indentation?! I will show you how to indent
  when I indent your skull!

Mike M wrote:
> ...you putting comments is up to you unless you are working with a team becaus
e then no one will have any idea what you are doing unless they sit an analyze i
t.  If i am writing a program for myself who cares if i am putting comments or n
ot?  Why should anyone care..its like im telling you your an idiot for adding co
mments..im just saying that i personally do not comment unless i know its either
a group project or my code is very long and complicated as you said....

1999\11\19@191624 by William Chops Westfield

face picon face
> if your coding for yourself and no ones ever gonna see it anyway who
> cares.  [if you can't read it in N years, that's just your own problem
> anyway.]

Completely true, but why create yourself problems when the effort to avoid
them is pretty small?  Yeah, I don't comment personal "one-offs" as
carefully as "work", but intentionally leaving out ANY comments is pretty
silly.  I prefer to think that any piece of code I happen to write is going
to make me rich(er) and/or famous some day, even if it's just a quick hack
today.  (for example, one semi-unofficial hack was a mainframe program to
download files to microcomputers using the XMODEM protocol.  Shortly
thereafter, it was used as THE download program at (the original)
WSMR-SIMTEL20 army software depot.  It was fame in a rather small circle,
but it was a pretty good feeling...)

BillW

1999\11\20@133939 by Mike M

flavicon
face
True, i was just talking about not commenting small simple code.  Anything compl
icated or long i always add comments.  And since any long tedious code that i do
write i am usually going back to it a year or two later to update it and of cou
rse i dont want to sit and decode the entire thing.  Like i said i understand wh
at everyone is saying and means, but everything on my part got twisted up..(prob
ably my fault :)

But anyway thats all folks..always a pleasure hehehehehe

mike ;)

Send someone a cool Dynamitemail flashcard greeting!! And get rewarded.
GO AHEAD! http://cards.dynamitemail.com/index.php3?rid=fc-41


'[OT] Re: How to write bad code - was Re: C vs. ASM'
2000\02\29@113446 by Larry G. Nelson Sr.
flavicon
face
Another way to insure backups of revisions is to get an HP CD Burner and
use their Simpltrax software that comes with it. It will backup changed
files in any directories you specify and all old revisions are also
available on the CD. This gives full revision history and you never
overwrite the older revisions. It works well for me and doesn't waste space
if nothing is changed. Fairly cheap insurance.



At 01:17 PM 11/18/99 -0800, you wrote:
{Quote hidden}

Larry G. Nelson Sr.
RemoveMEL.NelsonEraseMEspamEraseMEieee.org
http://www.ultranet.com/~nr

2000\02\29@181211 by Erik Reikes

flavicon
face
At 11:24 AM 2/29/00 -0500, you wrote:
>Another way to insure backups of revisions is to get an HP CD Burner and
>use their Simpltrax software that comes with it. It will backup changed
>files in any directories you specify and all old revisions are also
>available on the CD. This gives full revision history and you never
>overwrite the older revisions. It works well for me and doesn't waste space
>if nothing is changed. Fairly cheap insurance.
>
>

If you have an extra box and you're Linux savvy you should consider setting
up CVS.

It allows revision control and history, along with diff based merges of
files that multiple people are editing all over the network.

There is a java extension to it that allows it to work on about any
platform.  With cygnus stuff you may even be able to set up CVS ona windows
box but I've never tried it.

HTH

{Quote hidden}

Erik Reikes
Senior Software Engineer
Xsilogy, Inc.

RemoveMEereikesTakeThisOuTspamspamxsilogy.com
ph : (858) 535-5113
fax : (858) 535-5163
cell : (858) 663-1206

More... (looser matching)
- Last day of these posts
- In 2000 , 2001 only
- Today
- New search...