|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The last four lab assignments are
assembly language programs. The
programs must meet the specified
conditions to be turned in and graded. It is the student’s responsibility to meet these conditions. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Formatting and Mechanical Considerations for CS 330
Programs |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Formatting and Mechanical Considerations
for CS 330 Programs
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Programs
are due on the specified dates by 5:00 PM.
Any programs not turned in by that time are late and subject to
penalties for being late. 10% per day up to five days. After which the program will not be
accepted. Computers being down,
unavailable, etc. are not valid excuses unless in the extreme case that they
have been unavailable, etc. for a substantial period of time. Do not put off doing these assignments
until the night before. Note:
Program 4 is fairly difficult. Do not
wait on it. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The
professor may alter the conditions of the program assignments at any time so
long as he makes an announcement during any regularly scheduled meeting of
the class (either lecture or lab) or he sends an email to the entire class’s
NMU accounts. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Students must provide two identical copies of the
program. These are a printed copy of
the documented file and a computer file that will run on the professor’s
computer with all documentation included in the file. Please note this is not negotiable, the
programs must be identical in every way including spacing and
punctuation. The most efficient means
of providing the professor with an electronic copy is email. Due to issues with computer viruses the
professor will not accept USB drives from students. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The
name of the program must follow the convention xyzlabw.asm where xyz are your three initials w is the program
number either 3, 4h, 4d, 5, and 6.
This allows the professor to easily distinguish the authors of the
programs. For example, if the
professor were submitting the ascii code generator program he would name it
dwdlab3.asm. Failure to name this way
will result in a loss of points which will escalate each week. This condition will be altered if your
initials happen to create a reserved word problem. You will be aware of this if you are unable
to rebuild your program. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Certain mail programs place
attachments into the body of the email.
If your program does this, you may find that zipping the file before
you make it an attachment will usually solve this problem. You are encouraged to email the professor a
test program to ensure that your mail program and your word processing
software does not create an unreadable file for the professor. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
These two versions of the programs
(printed paper and electronic) must be EXACTLY
the SAME. This means you may not
write your name on it and hand it in.
Put your name into the program at the top as a comment. By the way, you must have your name at the
top of your program. It is recommended
that you print out the very document you send to the Professor. Note: The professor is aware that sometimes
tabs and other formatting controls are almost impossible to match. In such cases, your electronic tabbing may
appear slightly different. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Programs which are not IDENTICAL (both
electronic and paper) do not qualify as a valid submission of a program. Programs which do not open in the Quick Assembler environment on the Professor’s
computer do not qualify as a valid submission. Programs which do open but will not compile without error do not
qualify as a valid submission.
Programs which do not run
correctly do not qualify as a valid submission. It will not matter if the student had
the program working on a lab machine or on another machine, if it does not
run on the professor’s machine. Programs must use a font size between 12
and 16. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Students who submit programs which are not valid submissions will
be notified and provided approximately 48 hours to resubmit their
programs. In a resubmission two new IDENTICAL copies (electronic
and paper) must be resubmitted. Even
if the error which prevented the valid submission is a single character added
or removed, you must provide two new
versions of the program. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Programs which are not valid
submissions after two attempts receive a score of zero. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
While the professor is willing to
check that a program is working as required, he will not initial the program
as final until the program is working with the full documentation
included. He will not grade your
comments prior to program submission.
The professor will make brief remarks about the suitability of
comments, but he will not give you assurances that your comments are
sufficient ahead of time. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
What you must be Documenting
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
All
programs are to be fully documented as
outlined below. The majority of the grade for each
program is the quality of the documentation.
While it is understood that lab partners may choose to write programs
together; and therefore, would most likely have identical code, the
documentation is not to be written together and must be obviously
different. Simply changing a word here
or there is not sufficient for this. Partners
are warned that if the documentation is not sufficiently different, the
programs may have major points removed including being awarded no credit. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Even if you write
significantly different code than the professor provides to the class,
documentation remains the primary component of the grade. If the professor cannot easily follow and see
the student understands what the code is doing from the documentation, then
the program will be graded accordingly (i.e. the grade would be low). |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The professor would prefer that you not use assembly language
commands not covered in class. If you choose
to however, you must assume that your audience (another member of the cs 330
class) has never seen this command.
Therefore, your documentation must account for that. You must first explain the command in
detail and then explain what’s its role in the program is. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Keep in mind the point of
documentation is to allow another person (or perhaps yourself after a long
period of time) to understand why your code is doing what it is doing. All programmers find viewing another’s raw code
confusing at first. Everyone has their
unique way of approaching a program.
Documentation allows another to quickly understand the purpose and the
method by which a piece of code is functioning. This allows another person to modify or
re-use elsewhere as needed someone else’s code. No
one likes doing documentation, but it is necessary. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
As you write documentation keep in
mind WHY rather than WHAT. Anyone familiar with a language will
quickly see what the action of the line is.
The question is why do that line at all? Why do that line at this point in the code
rather than earlier or later? Think
about those questions as you write the documentation. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Documentation is achieved by writing
comments after the code. First one
places a ; (semicolon) to inform the compiler that what follows is
documentation and not program. The
best method of documentation would be to have a brief statement at the
beginning of the program explaining the purpose of the program as a whole. Then, at the start of each section of the
program a line or two outlining that section’s purpose and how it is
done. Finally, individual lines should
be as fully commented as possible. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Some procedures require several code
lines to carry out and individual lines are not sensible to be commented on,
in such cases you may comment on the lines as a whole, but be clear in your
comments of how all lines are needed.
This occurs when a single task or function requires two or three lines
to carry out, such as the getting of input from the keyboard, or the printing
of characters to screen. Jumps usually
have at least two lines related. For
example jc Label1 is of course jump if carry flag is set, but this usually
follows a compare statement. So
comment on the pair, for example: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The professor is
fully aware of how much code he is providing for each of these four
programs. That is why documentation is
so important. You are convincing him
that YOU understand why the program works. Less explanation is not better!! If it is not clear to the professor that
you have this understanding, points will be taken off. Consider that if you choose to do the least
work you think is possible, the professor has the right to do the least work
in determining whether you understand something or not and could choose that
you do not understand and simply give you a low score. If you wish a high score, show off your
knowledge. Do more work, not less. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
While the professor in some class
examples provides minimal documentation, you are not permitted this
luxury. You must fully explain what
you are doing. Just because the
professor kept the documentation brief does not give you the right to copy
his brief comments and indicate since he wrote this, it is sufficient. Remember part of the reason for brevity in
the first place in his instructions is to not hand you the documentation in
addition to the code. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Use proper writing and grammar styles
in your documentation. Do not use
IM-speak! Full sentences are
preferred. The goal is to explain the
code fully enough so that someone who has a basic knowledge of assembly
language, but does not know what the program goals are ahead of time can read
the documentation and understand what you are doing and how the program
works. Again, you are demonstrating to
the professor that you understand what is happening. Making inaccurate statements obviously
hurts this and points will be lost.
Use the proper terms and vocabulary.
Bit means 1 binary digit. Byte
means 8 bits not 4 bits! IF you say
byte and you mean nibble, you are just wrong. If you say ch, but you really
mean cl, again, you are wrong. So PROOFREAD!!!! And SPELLCHECK!!! |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Once you have
documented a procedure in a program within the same program you may briefly
point out that the same thing is happening in subsequent uses of that
procedure. In future programs you may
be allowed to be relatively brief if the professor feels you have
sufficiently explained this in early programs. Still in a later program the first instance
of the procedure should entail some explanation. Unless comments receive an excellent
grade, improve the comments each time a program is submitted. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
What to avoid in documenting
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
First of all consider giving a driver
directions when they have no idea where they are going. Is it useful to describe things that they
are nowhere near? When you are driving
across the UP, describing turns that you will eventually get to in New York
City are not likely to be very useful.
Similarly describing things that will happen later in the program is
not so useful. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Never say “use later” or
“for later use”. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Remember
documentation is not about making your life easier, it is about making the
reader’s life easier. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Watch the tone of your comments.
Do not try to be funny. Do not
be sarcastic or annoyed in your tone.
Points will be deducted. This
is not your blog, this is not for your enjoyment. This is an assignment. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Neatness counts. Do not turn in programs that look like
crap! Warning:
the assembler will create run over lines which do not look good. Be sure that you never go past the 80
column. The program will show what
column you are on. Notice in the
examples of good documentation below that spaces are used to break the
program into logical sections related to function. Notice also the uniform spacing of where
the comments started. If the
professor cannot follow your comments because they are too intertwined with
code, even if the comments are 100% right, you will be deducted points. You do not have to comment the pre and post
code required to make your programs run in the assembler. But remember the programs will not run
without this code. Do not get hung up on Flags. They are useful, but remember the reader
has had CS 330 and knows what they are and do. Instead of fixating on what the carry flag
is, it is better to discuss what is happening, for example JC is jump if the
carry flag is set, don’t tell me that.
Tell me why you are jumping.
For example, we jump here if the number is less than 30 because that
means we have an ASCII code that is not in our valid range. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not tell what the action of a line
is. For example, telling that “mov bx,ax” copies ax into bx
will get the DUH comment written by it. Do not indicate that “add al,30h” is adding
30 hex to al. Again DUH. Explain WHY. Why is a line in the program? That is the key to writing comments. If the line has no purpose, take it out.
(Put a “ ; ” in front of the line and try running the program.) If the program will not function correctly
without the line, then there is a reason the line is needed. Figure it out. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Points will not usually be deducted
for occasional bad programming. But if
the program is horrendous enough (in the professor’s opinion) then points
will be deducted. For example, points
will not be deducted for an occasional line that serves no purpose, but if
you have too many, then points may be lost.
Do not ever jump to the very next line of a program. If you are jumping to the next line change
your logic. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not try to sound impressive. We print on a screen not a console, we use a keyboard. Keep it simple
and straightforward. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not write a section
summary and then say the exact same things on each line. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not write to get
points. Write to explain. Writing to just add length is not going to
increase your score and likely will decrease your score. It is about getting the appropriate
information conveyed, not getting some number of words or lines down. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Finally, have a friend read over your
documentation and see if they understand what you are doing. If they ask you questions, then you know
what you need to explain more. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From
Recent Semesters: These are things you
should not do. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not tell the professor
to go to another section for more information. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Don’t use a
comment such as “we are doing something to make it easier or better.” That is vague be specific why you are doing
things. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
“We set up certain registers to be certain
parameters to ensure success of our program.” |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not change the
conditions of the program (i.e. use space to end program immediately). |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
These things you should do. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Use proper punctuation to
separate comments. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Comment on commands in order
of their occurrence. The first time a
command or function is introduced, explain it. The idea that the professor or reader will
get it later is not acceptable. Do not
say … doing for later? Why, what will
happen later? Do you wish to be kept
in the dark? |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Think about what the code
is doing. For example bx is a register
that has many uses, think about what the current use is. Push Bx is not because BX needs to be
saved, it is because the contents of BX which is something we are working on
needs to be saved. What are they? Why do they need to be saved? |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PROOFREAD “mov dh, 01h ; putting 1 into dl” Don’t do this. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Understand that looping
will have different variables each loop. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Use “ ” around Logic
functions so that the meaning is understood.
“AND” means do a logical AND instead of the usual conjunction and. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Please use Most Significant digit and Least
Significant digit rather than first and last digit or first and second
digit. Is the most significant the
first or second digit? |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not get bogged down on
what flags are doing. Do not quote a
manual says a command is doing. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Examples of Documentation (Good and Bad)
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
An
example of bad looking programs: not
neat, comments hard to separate from code, etc. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
begin: mov ah,01h ;01h is moved into
ah which is an instruction to ;wait for a key to be pressed then
places ASCII ;code for character pressed into al and
prints onto ;screen. int 21h
;The interrupt call(int 21h) looks into ah and sees ;the value 01h which waits for a key to be
pressed ;then places ASCII c ode for character pressed into ;al and prints onto screen. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do
Not Piccard! This is the extreme example of multiple
lines being commented as a group. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Do not do the following: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Instead do the following: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Example of bad
choices for jumps: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
jc Proceed jmp GetKey Proceed: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
instead use a single jump |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
jnc GetKey Proceed: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Convoluted jumps |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cmp ax,
bx ; jc
NegativeNumber FinishCalculate: sub
al, bl das mov bl,
al ; mov al, ah
; sbb al, bh
; das
mov
bh, al ; jmp DoCalcPrint ; Jump down to print the
answer to the console. NegativeNumber:
; push
ax mov ah,
02h mov
dl, 2dh ; int 21h mov
ax, bx ; pop
bx ; jmp
FinishCalculate |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Better would be: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cmp ax,
bx ; jnc
FinishCalculate push
ax mov ah,
02h mov
dl, 2dh ; int 21h mov
ax, bx ; pop
bx ; FinishCalculate: sub
al, bl das mov bl,
al ; mov al, ah
; sbb al, bh
; das
mov
bh, al ; jmp
DoCalcPrint ; |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
More
examples of bad documenting from actual students in previous semesters: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mov
CL,04h Begin:
mov AH,01h ;command to wait
for key to be pressed int
21h ;execute AH = 01h command
(save & printed) mov
CH,AL ;save input from AL in CH mov
AH,02h ;command to place ascii char
on screen mov
DL,3dh ;place "=" = 3d
(hex) in DL int
21h ;execute AH = 02h to print DL
= "=" on screen mov
AL,CH ;place from CH to AL shr
AL,CL ;shift AL by CL (04h) to right |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Examples of what to do:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
; Dr. Dave Donovan ;Program 3 Version 2004- March 23 ;This program will be an example program
for demonstrating proper documentation ;comments. ;This program will create noises on an
ibm personal computer using the computer’s internal ;speaker. .model tiny .stack .code .startup ;
***** put program instructions
here ******************* ;This section initializes several
parameters that are used by the program. mov bx,2000h ;This
value is used to set up looping later in the program. The ;size ;of this value will
determine the amount of time the ;computer is ;occupied thereby
sustaining a current to the ;speaker to create the tone. note: mov cx,bx ;cx
will be used as a time counter. So the
initial value is now ;placed in cx. ;This is the main part of this
program. Speaker information is
determined and then modified ;to allow the user to create a variety
of noises. Note: actual tones require
substantial ;calculations involving the clock
speed of the computer. in al,61h ;Get
the current speaker configuration. Memory location 61h is ;reserved for the internal
speaker. and al,0feh ;The
value of bit 0 determines if the speaker is controlled ;internally ;or
externally. ;Set bit 0 to 1 for external
control of speaker xor al,02h ;If
bit 0 is set to external control then bit 1 determines if current ;flows to the speaker or
not. Current flowing to the speaker ;moves the speaker cone in one
direction. No current relaxes ;the speaker cone back to its
original position. This vibration of ;the speaker cone creates
sound. The “xor” toggles the current ;bit. This creates our
vibration. out 61h,al ;The
speaker register has not received this information that bit ; 0 is now 1 and bit 1 was
toggled. This command sends that ; information to location 61h
which is the speaker register. delay: dec cx ;The
decrementing of cx creates a time delay to space out in ;time the
vibrations of the speaker. jnz delay ;If we have not finished
decrementing cx we continue to wait so ;we jump back and continue
decrementing. When cx is zero we ;have finished creating the
tone. ;Now that a tone was issued through
the speaker we want to see if the user wishes to ;continue. If they do, we will also allow the user to
change the tone emitted. mov ah,0bh ;Check
if a key was pressed. If key is
pressed, al=FF int 21h ;
IF no key is pressed al=00 inc al ;We
make al zero if a key is waiting to allow the jump command ;on the next line
to continue created the same tone. If
a key is ;pressed, we have two options.
If the key was the “@” key we ;will end the program. If not, we will use the ASCII of the key
;pressed to create the new delay for a new tone. jnz note ;Loop
back if no key was pressed. mov ah,07h ;If
a key was pressed get the key code but do not display ;anything on screen. int 21h cmp al,40h ;Check
for end key "@" jz done ;If it is then end the
program. mov ah,00h ;Otherwise we will modify the
ASCII code to make a reasonable ;delay value. mov cl,0ch ;We
must load a value that will be used to multiply the ASCII ;code. On the faster shl ax,cl ;machines
available 2 ^12 is reasonable. mov bx,ax ;Since
we are going to jump back to the beginning we store this ;value in bx as above it will
be moved into cx. Note since cx is ;decremented, we need bx to
hold the value so if we wish to ;continue with the tone the
value has not been lost. jmp note ;Jump
back to continue the program. done: ;We have received the key
telling us to quit the program so now ;we do. ;
************
*********************************
********** mov ax ,4c00h ;quit int 21h end |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional
GOOD documentation examples from a student’s code. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
; CS330 - F07 ; Student Name ; Program 4Decimal ; ; This program will work as a decimal calculator,
accepting two 4 digit sets of ; hexadecimal digits (0-9) and
performing either addition (+) or subtraction (-). The ; program will quit on @. ; mov
cl, 04h ;cl will be used for
shifting purposes. Setting to 4 ;
allows to quickly manipulate/move nibbles. Start: mov
bx, 0000h ;bx is where the numbers are
stored after we clean them ;
of ASCII code. Since we're starting,
we want to ;
zero this value so nothing becomes contaminated. Gkey: mov
ah, 07h ;Grab the ASCII value of the
key pressed using int 21h. int
21h ; Setting AH to 07h
allows us to grab the character ;
input without echoing it to the screen.
Need this ;
so that we can check if it's a valid hexadecimal. ;
Will print the key once it's been validated it. ;Anything that gets past these
comparisons must have fallen in the 0-9 range. mov
ah, 02h ;Since we've got this far,
the value we have must be good. mov
dl, al ;Print it using int
21h. Use the 02h option of int 21h to int
21h ; print what is in dl to
the screen. Move al, our key ;
value, to dl & print. ;We
have now printed the key which was pressed to the screen. We still have the ;
ascii value for that key, not the actual decimal value of the key. As an ;
example, if the key '6' was pressed, we currently have '36' in al. For printing ;
this is great. For doing mathematical
calculations, '36' is useless to us. We ;
need to take this ascii value and convert it to the equivalent decimal value
so ;
we can perform calculations on it. sub
al, 30h ;We'll start by subtracting
30h from our value in al. If ;
the key pressed was a number, subtracting 30 will leave ;
only the actual number. Example- If 4 was pressed, we ;
would have 34 in al. Subtracting 30
leaves 04, which we ;
need. ;We
now the actual key that was pressed located in the LSN of AL. Since we will ;
accepting up to 4 digits per set of numbers, we need to save this somewhere. ;
Will be using BX to save these values.
Each time a new key is to be added, will ;
shift the previous values left in BX.
After the 4th value, any new values will ;
drop the oldest value out of BX.
Before we can add it to BX we need to do one ;
last sterilization. Pack: shl
bx, cl ;Have a new number that
needs to be placed into BX, shift ;
the contents of BX to make room for it.
Using cl, which ;
is set to 04, so that we can shift BX by one nibble. or
bl, al ;Copy our new, freshly
cleaned value into BL. Use OR jmp
Gkey ; instead of MOV because we
need to keep the MSN that is ;
already in BL. Had we used MOV, it
would have erased ;
the value of the MSN. Once done
copying the value into ;
BL, go grab a new key. ;Done printing the answer, get ready
for a calculation by printing a carriage ;
return and a new line. mov
dl, 0Dh ;Print the carriage return. int
21h mov
dl, 0Ah ;Print a new line. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A
Final Example to illustrate what documentation is all about. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Consider the following program: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SO
what does this do, how and why? |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The following is the all too common
kind of documenting provided by students who would later complain about a low
grade: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Compare that with the following
documentation. This is what would earn
a higher grade: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;This program will read in the current
temperature that the cryostat is maintaining at the ;time this program is run. The temperature will be read in as four
parts, hundreds, tens, ;ones, and tenths of ones where the
actual temperature is in units of Kelvins.
The hundreds ;digit is stored at memory location
0200h, the tens digit at memory location 0201h, the ones ;digit at 0202h and the tenths of ones
at 0203h. ;Program Version 2010-11-24 by D.W. Donovan |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;Initializing of the Serial port Com2:
we need to establish the serial protocol of 8 data bits, ; 1 stop bit and no parity. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;Issuing of CDAT command. This is the command that the cryostat must
receive for it to ;output its current temperature. The firmware of the cryostat requires
sending 3 periods(.) ;followed by the letters C, D, A, and
T. Finally one must send the question
mark(?) and a ;carriage return and linefeed
characters for the cryostat to respond to the request. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;This section now reads in the four
digits of the temperature and stores them in the ;appropriate memory locations 0200h
through 0203h. Sin is the subroutine
that reads the ;serial port incoming data. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;This is the Serial In
subroutine. This reads the serial port
for incoming data and when it ;receives it, the data is stored in ch
and then the routine returns to where it was called from. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
;This is the Serial Out
subroutine. This checks for the
transmitter to be ready and able to ;send data. Then it sends the data provided out of the
serial port. Afterwards it returns to ;the point of the program from which
it was called. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
An
additional example of bad documentation ;Student ;CS330 .model
tiny .stack .code .startup ;
***** put program instructions
here ******************* mov cl,04h ;here we are putting
4 into cl, so that we can eventually ;so we can eventually use this to shift
the left hex value of al to the ;one on the right so we can use the data begin: mov ah,01h int 21h ;moving 01h into
ah so we can execute the take in a key command, this command also echos ;what we put in so that it also appears
on screen mov ch,al mov dl,3dh ;this group of
commands is loading what we get from the answer of the first input mov ah,02h ;and stores it into
ch so we can use it later for converstion int 21h ;we then are
moving 3dh into dl, which is the ascii code for the - symbol and then ;we put 02h into ah and execute the
interupt, which prints out the ASCII code ;of the hex digits in DL (which is our -) mov al,ch ;here we are taking
our original value from ch, which is where we stored it, and putting shr al,cl ;it back into al,
there we are moving the higher part of al to the lower part, and then adding add al,30h ;30 in hex to said
value, this is done so that we can then after move into the letters in the
ascii chart and avoid things cmp al,3ah ;like the colon and
greater than sign, if we fall in those signs it jumps us ahead to the letters
in the ascii code chart jc hdig ; from tripping
the carry flag add al,07h hdig: mov dl,al ; here we are moving
our al in dl so that we can print out
the first digit of the hexadecimal mov ah,02h ; with the next
interupt command int 21h
mov al,ch ;now we take the
original value again, move it back into al, except we are getting rid of the
higher digit and al,0fh ;by anding it with 0,
we then repeat the proccess seen above of adding 30 in hex to our al register
to get the add al,30h ;next number we will
be printing to the screen, and once again we have to compare it to 3ah, to
make sure we are cmp al,3ah ;not falling into the
territory of the wierd symbols that cannot be a hex digit jc ldig ;if we do fall
into that territory we add 7 to our digit to get back to the letters add al,07h ldig: mov dl,al ;here we will take
our new al value (the number/letter we wish to print) to the dl register so
we can use mov ah,02h ;an interupt to print
it to the screen int 21h mov dl,0dh ;this line prepares
the dl regiester to excecute a carriage return int 21h mov dl,0ah ;and here we are
skipping down to the next line, so our program does not get cluttered int 21h mov al,ch ;now we once again
move our original value into al, if it happens to match the ascii code for
the cmp al,40h ;@ symbol then we
will be exiting the program, this is done by comparing it to 40, if they are
the same jnz begin ; our zero flag will
be tripped, and we will walk out of the program, otherwise we will loop back
to the start ;
************
*********************************
********** mov
ax ,4c00h ;quit int
21h end |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|