Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!utgpu!water!watmath!clyde!rutgers!jvnca!njitsc1!argus!ken
From: ken@argus.UUCP
Newsgroups: comp.misc
Subject: Re: Assembly Language
Message-ID: <1005@argus.UUCP>
Date: Tue, 18-Aug-87 09:09:12 EDT
Article-I.D.: argus.1005
Posted: Tue Aug 18 09:09:12 1987
Date-Received: Thu, 20-Aug-87 01:33:25 EDT
References: <892@edge.UUCP> <2840@phri.UUCP>
Organization: NJ Instit. of Tech: TEIES Project
Lines: 64

In article <2840@phri.UUCP>, roy@phri.UUCP (Roy Smith) writes:
> 	My experience has been that most assembler code has one comment
> per statement, often not very useful at that.  A typical example might be:
[example removed]
> 	Of course, this is not to say that there aren't assembler
> programmers who comment the algorithm instead of translating the opcodes
> into english, but they seem rare.  In fact, I would guess that in most
> assembler courses (are there any of these anymore?) the above code would
> get a positive nod from the instructor because every line had a comment,
> just like it is supposed to.

One instructor at this school was infamous for his insistence that every
line of assembler must have a comment on it.  My preference was to put
what the routine did in a block at the beginning, and then note the
functions of the branch statements only.  After I got points taken off
for not putting 'proper' docomentation in I wrote a program that
checked each line for a comment.  If there was one the line was ignored,
otherwise a comment would be generated from the assembler code.  For
example, if the op code was 'LR R1,R2' the comment generated would be
'* load register R1 with R2'.  Yes I know that this comment is useless,
but when the principal grading criteria is how well I follow the
instructors inane documentation rules rather than the correctness of the
program and/or the usefulness of the comments, I ran this program to
generate the comments.

> 	That's also not to say that that writing in a HLL automatically
> make it easier to write useful comments.  I've seen lots of C code that I
> couldn't figure out for the life of me with random incoherent comments that
> don't do anything to help describe what's going on.  Ditto for Fortran,
> Basic, Pascal, Lisp, etc.

One thing that has bugged me about a lot of programs I've seen is that
people seem to abor using variable names that go with the function of
the variable.  Sometimes they will comment at the declaration, but it
would be far better if they chose names that made sense.  An example
follows:

i     -- co-efficient of friction
ii    -- total mass of object 3
iii   -- x coordinate of object 3
iiii  -- y coordinate of target
iiiii -- final speed of system

Yes the function of the variables is commented, therefore it gets a good
nod from the grader, BUT THE VARIABLES MAKE NO SENSE.  Granted I tend
to go overboard by declaring the variable 'final_system_speed' (I *LIKE*
REXX), but I don't need a lookup table to find out what the variable
represents.

Granted, being at a school I see a lot of people making close to their
first attempts at programming.  But I've seen similar stuff on senior
and masters projects as well.  I hope that the programs written out
in industry are better.


> Roy Smith, {allegra,cmcl2,philabs}!phri!roy
> System Administrator, Public Health Research Institute
> 455 First Avenue, New York, NY 10016



Kenneth Ng: Post office: NJIT - CCCC, Newark New Jersey  07102
uucp !ihnp4!allegra!bellcore!argus!ken *** NOT ken@bellcore.uucp ***
bitnet(prefered) ken@orion.bitnet