Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Danger, danger Will Robinson (documenting code)

by jepri (Parson)
on Mar 29, 2001 at 17:44 UTC ( #68092=perlmeditation: print w/ replies, xml ) Need Help??

I was just browsing the net (isn't that a common start to so many stories thesedays) when I came across something that seemed worth sharing here. It was on the page of a microchip site and was part of an article on assembly language coding. I scanned through it and was caught by the authors little sidetrack into comments on documentation.

Since this has been a hot topic at the monastery at various times I was intrigued to see the same comments being used in discussions on documenting assembler.

The thing that prompted me to bring it up here was my thought that (in my mind) these two languages (perl and asm) could hardly be further apart, but many of the points made seem to apply to documenting both. To my mind if there are similarities between two things that appear to be very different, then there is something to be learned. Plato is my hero.

Please post your own memories of horrible or wonderful code that you have dealt with, and don't worry if your points contradict each other (or someone else), since the author manages to compain both about too much documentation, and not enough (presumably not in the same code sample).

For myself, I have spoken every point on this list at least once, with the addition of:

The author had an appreciation of tacky science fiction that I (unwillingly) became familiar with.

Please read the authors experiences reproduced below and post your own memories of code that you considered poorly documented.

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

When was the last time you worked on someone else's assembly program? Were you able to work comfortably with the code and attending documentation, or did it leave you on the verge of a slanderous rampage? The complaints I have voiced most often (and loudly in an empty lab) are these:

  1. This program does not have enough high-level documentation—it's all details.
  2. This program has wasteful documentation of its simplest parts.
  3. This program is packed with spaghetti code and interlocking loops.
  4. There is not enough information here to even assemble the original source (makefiles, etc.), much less make changes.
  5. The comments are written in a grammatically incorrect format, eliminating important words, such as verbs and articles, for brevity.
  6. This programmer wasted his time on long-winded comments that are as extensive as the source code. Why shouldn't I just skip the comments and decipher the actual code?
  7. This flowchart or state chart is out of date with reference to the current source.
  8. (Add your favorite gripe here.)

____________________
Jeremy
I didn't believe in evil until I dated it.

Comment on Danger, danger Will Robinson (documenting code)
Re: Danger, danger Will Robinson (documenting code)
by jorg (Friar) on Mar 29, 2001 at 19:07 UTC
    This is one I came across recently:
    Copying and pasting code snippets together with the comments (helpfull comments that is), then change the code but don't bother updating the comment..
    Guaranteed confusion when updating a rather big sourcetree, after all, one checks the comments first to see if a section of code needs updating... *sigh*


    Jorg

    "Do or do not, there is no try" -- Yoda
      Adele Goldberg, one of the principals behind Smalltalk and later founder of ParcPlace Systems, coined a term that covers copying chunks of code but neglecting to fix comments. She calls it "Rape and Paste Programming".

      It's an expression that grabs your attention and forces you to stop and think.

(jcwren) Re: Danger, danger Will Robinson (documenting code)
by jcwren (Prior) on Mar 29, 2001 at 20:43 UTC

    I do a fair amount of assembly programming with x86 and 8051 family, and have experience in about 20 different major processor families. My *biggest* peeve is people who refuse to put the name and version of the tool chain used to build the product in the source file (not to mention whether they used NMAKE, DMAKE or TMAKE under DOS/Win32).

    As you may or may not know, for any given processor, there are a number of different assemblers. *Generally* the processor instructions remain the same, but the pseudop-ops (for macros, page ejects, equates, etc) often differ. Someone sends you a source file, and you have no idea what tool was used to assemble it. Sometimes, when you have a lot of experience, you can recognize "Oh, it's MASM, or TASM, or OPTASM". Many times though, especially if it was someone who used one of the 50+ freeware assemblers, you'd have better luck rolling dice.

    I'm guilty of not doing that for Perl code. Luckily, Perl is a lot more portable than assembly source code is. On the other hand, people can use 5.6-isms that someone who doesn't use 5.6 may not recognize.

    I always list the tool chain for my Forth, ASM, and 'C'-ware. I think I shall start at least indicating what it was run under when I wrote it, for my Perl scripts.

    --Chris

    e-mail jcwren
Re: Danger, danger Will Robinson (documenting code)
by Malkavian (Friar) on Mar 29, 2001 at 21:01 UTC
    This is a bit of a current one for me:
    A lot of what I'm currently doing is reverse engineering existing code. Some of this is Perl. Some of this is actually very nice perl with documentation and descriptions of callers, arguments etc.
    However, most of the code I have to deal with is old C shell (some BASH or ZSH) or distinctly flakey Perl (worse than mine by far, and I'm no guru).
    This latter stuff has no documentation, and, being coded by volunteers over time, the coders themselves had very little view of the big picture, have moved on, and been replaced by other volunteers who've hacked the scripts to do more what they think it should do.
    Examples of behaviour are:
    C shell script. Has no documentation of what should be passed to it as an argument (or agruments). The arguments are actually referenced in obscure parts of the script. Various variables are named correctly in parts of the scripts, but 're-used' to mean completely different things if certain conditions are met.
    Many of the scripts run correctly only if run as a particular user in a particular directory with very specific arguments (i.e. having a path/name of something it doesn't expect. It still builds up names of intermediary files it expects to find from what you enter, can't find them, and tells you it can't find the original file you specified, rather than the file it's trying to find.
    These are simple things to document (well, at least the expected arguments are easy, and little bits to say what each part of code does).
    Personally, the code I end up 'signing off' has a header to say what is it, what it does, the arguments it takes and what the end result it produces is.
    Each subroutine is documented as args in, purpose and return value.
    Every time I change code that's "In production", I make a quick comment to say 'I changed this code because... on date whatever'..
    Just a little documentation is a wonderful thing.

    Malk
Re: Danger, danger Will Robinson (documenting code)
by WebHick (Scribe) on Mar 30, 2001 at 08:42 UTC

    It doesn't sound like anyone had mentioned this, but I'd like to add Parental Commenting to the list. When I started learning Perl, I downloaded a program off the Internet (I learn best by example) to help. I saw things such as:

    #Don't change this. $a = '1';
    #This needs to be here. You can change it if you want $b = '5';
    and the famous:
    #Set this to 1 if your system implements it. $x = '0';

    The comments make me feel like the author is telling me not to play in the street because there's "stuff" in the street. He blindly assumes that I know the "stuff" are cars and that I know the make and model of each one.

    Update: Due to several complaints, removed signature

    Sarah

Re: Danger, danger Will Robinson (documenting code)
by yakko (Friar) on Mar 30, 2001 at 09:55 UTC
    In the AppleII world, I got to play that "What Assembler (and OS) is it?" game... but on the whole, decent listings included this information, or it was a dead giveaway (ie, a big fat "MLI = $BF00 ;ProDOS MLI entry" is a good indicator that this program isn't for DOS 3.3...)

    A recent peeve of mine has been not just what comments say, but what one names the variables. This, IMHO, is just as important as meaningful comments -- perhaps even more so. Check this out:

    # handle CTCP {LOOK,OGLE} sub _lookpm { my $boo=shift(@_); my @x=split(/ /,$boo); my $y=(split('!',$x[0],2))[0]; my $z=IRC::get_info(3); my $man=IRC::get_info(1); my $booya=$x[2]; . . .
    Even though this snippet is my own that I just altered extremely to provide example, when I saw very similar code in another script when I was just starting out in perl, it proved that variable names -do- matter, and -do- provide insight into the program's workings. It doesn't have to be ugly, tho:
    # handle CTCP {LOOK,OGLE} sub _lookpm { my $line=shift(@_); my @pargv=split(/ /,$line); my $who=(split('!',$pargv[0],2))[0]; my $serv=IRC::get_info(3); my $nick=IRC::get_info(1); my $context=$pargv[2]; . . .
    . . . and it's still debatable as to the usage of some of these vars. I'll have to work on cleaning it up. :o)

    Which would you rather have the pleasure of trying to understand?

    --
    Me spell chucker work grate. Need grandma chicken.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://68092]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (6)
As of 2014-09-18 05:38 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    How do you remember the number of days in each month?











    Results (108 votes), past polls