help commenting code

[gammaman]

Hello all.  I am taking a course in Computer Architecture.  Part of that course is assembly.  We are not learning the language but just understand how it pertains to computer architecture.  Despite this I was given an assignment in which I must comment 3 programs given to me.  I am finding this very hard since I do not already know the language and it is not being taught to us.  Can someone please help me accomplish this.  I have already started to comment, but please feel free to correct or criteque me.

Code Select Expand


Title prog1 Define and display numbers
;Name: Matthew Fierro
;The output will be the ASCII character associated with the data
.model small
.stack 100h
.data ; data segment
       list db 31h, 32h, 33h, 34h
.code ; begin code
        main proc
        mov ax, @data   ; initialize data segment
        mov ds, ax      ; moves the value from ax into ds
        mov dl, [list]
        mov ah, 2       ; subroutine number 2   
        int 21h ; calls the dos interrupt
        mov dl, " "
        mov ah, 2       ; put 2 into ah     
        int 21h ; calls the dos interrupt
        mov dl, [list+1]
        mov ah, 2       ; put 2 into ah
        int 21h ; calls the dos interrupt
        mov dl, " "
        mov ah, 2       ; put 2 into ah
        int 21h ; calls the dos interrupt
        mov dl,[list+2]
        mov ah, 2
        int 21h ; calls the dos interrupt
        mov dl, " "
        mov ah, 2
        int 21h ; calls the dos interrupt
        mov dl, [list+3]
        mov ah, 2
        int 21h ; calls the dos interrupt
       
        mov ax, 4c00h ; end of processing
        int 21h ; calls the dos interrupt
        main endp ; end of procedure
        end main ; end of program



[dedndave]

lol - sounds like the prof has found a back-handed way to make you learn assembler
at the same time, he's teaching you to remark your programs (a good first lesson)
truthfully, I can't see how you can learn architecture without a grasp of basic assembler, anyways
even though assembler is machine specific, you are going to be dealing with intel-based processors eventually

just so you understand, we don't generally do homework for students
I will give you one freebie

every programmer has a different style
normally, I would not remark every line in such detail
it is safe to assume that the reader knows the basics
otherwise, they'd be reading playboy
for class, mine might look like this...

        TITLE   prog1

;display a list of numeric characters
;Name: Dead-end Dave

;display ASCII numeric characters from a list, seperated by spaces

;------------------------------------------------------------------

        .MODEL  small

        .STACK  100h        ;256 byte stack

;------------------------------------------------------------------

        .DATA

ChrList db      '1234'

;------------------------------------------------------------------

        .CODE

main    PROC

        mov     ax,@data           ;get data segment
        mov     ds,ax              ;into DS register

        cld                        ;direction = up
        mov     si,offset ChrList  ;address of list
        mov     cx,sizeof ChrList  ;number of characters

Loop1:  lodsb                      ;character in AL
        push    cx                 ;save count
        xchg    ax,dx              ;character in DL
        push    si                 ;save index
        mov     ah,2               ;function = display character
        int     21h                ;DOS function call
        mov     dl,' '             ;space character
        mov     ah,2               ;function = display character
        int     21h                ;DOS function call
        pop     si                 ;recall index
        pop     cx                 ;recall count
        loop    Loop1              ;until done

        mov     ax,4c00h           ;terminate, return code=0
        int     21h                ;DOS function call

main    ENDP

;------------------------------------------------------------------

        END     main        ;entry is main

by the way - "list" is a reserved assembler word - can't use it for a label

[gammaman]

Thanks.  Actually I have quite an extensive background.  I have a BS in Computer Programming and Information Systems.  I am very familar with high-level languages like Java and C#.  However I just recently started my masters in Computer Science.  I was placed in a few undergraduate courses like computer architecture because my background was lacking.  I am fully aware of proper commenting techniques.  See the course I am taking is a crash course this summer.  I am trying to knock out all of my prerequistes so I can become a full-time graudate student in the fall.  The professor told us it would take him 1 or 2 semesters to teach us assembler, so instead he is just having us comment some programs to see that we understand "how to computer works".

[dedndave]

oh - you might want to add these 6 lines between loop and mov ax,4c00h

.
.
.
        loop    Loop1              ;until done

        mov     dl,13              ;carriage return
        mov     ah,2               ;function = display character
        int     21h                ;DOS function call
        mov     dl,10              ;line feed
        mov     ah,2               ;function = display character
        int     21h                ;DOS function call

        mov     ax,4c00h           ;terminate, return code=0
.
.
.

actually, there are more direct methods of displaying the string

if the string were defined as:
ChrList db '1 2 3 4',13,10,36

you could display them all at once with

mov ah,9
mov dx,offset ChrList
int 21h

[dedndave]

you should become very proficient at assembly language
you will never regret the time spent getting started
it will give you much clearer insight to the inner workings of processors and operating systems
although - this is a 16-bit program - i suggest you learn 32-bit programming

btw - i am an EE with 30+years
if i was going to hire an MS, I would expect him to be proficient in windows 32-bit assembler
even if the software was to be C or any other language
you have to pay if you want an MS instead of a BS

[gammaman]

really, based on what professors have told me, Computer Science people only need a "general" idea of hardware because CS is all software.  According to my prof's it is the Computer and Electrical  Engineers that need to be proficient in hardware.

[gammaman]

Oh one last thing.  I am currently running masm on a 32-bit operating system.  Before that I was attempting to run it on a 64-bit system and was getting an error during the assembly process.  Any reason why?

[dedndave]

well - i am not sure - i do know that 16-bit code will not run on vista 64
maybe, it won't let you compile it, either

yah - when i was young, i wanted to get a phd in physics - lol
not much money in that, but it is what interested me
looking back, a business admin degree would have been more sensible and probably much easier to get
i think the guys with a technical degree and a business degree are most successful, monitarily

[gammaman]

That is ironic.  I also have full intentions of getting a PHD.  I love to teach and help others.  I also like taking lead roles. Professors have very secure jobs, especially in today's economy.  I mean really have you ever heard of a professor being let go.  It is a win win situation for me.  Write now I attend NYIT.  In the future I hope to attend NYU for my PHD.

[dedndave]

ahhhh - to be young again - lol
i wish you all the best

[gammaman]

are these comments any better, are they correct

Code Select Expand


Title prog1 Define and display numbers
;Name: Matthew Fierro
;The output will be the ASCII character associated with the data
.model small
.stack 100h
.data ; data segment
       list db 31h, 32h, 33h, 34h        ; use db to define each element as 2 byte
.code
        main proc
        mov ax, @data ;copy the address of the data   
        mov ds, ax      ;segment(@data) into the ds register
        mov dl, [list]
        mov ah, 2        ;int 21 function 2 displays the characters in dl     
        int 21h         ; calls the dos interrupt
        mov dl, " "             ; puts a space 
        mov ah, 2         
        int 21h
        mov dl, [list+1] ;copy second byte to dl
        mov ah, 2       
        int 21h
        mov dl, " "
        mov ah, 2       
        int 21h
        mov dl,[list+2] ;copy third byte to dl
        mov ah, 2
        int 21h
        mov dl, " "
        mov ah, 2
        int 21h
        mov dl, [list+3] ;copy fourth byte to dl
        mov ah, 2
        int 21h
       
        mov ax, 4c00h ; end of processing
        int 21h
        main endp ; end of procedure
        end main ; end of program


[Neil]

Everyone has their own style of commenting a program, so I'm not going to say how I would comment it, but what I will tell you is that a comment is for explaining what the program is doing or about to do, what you shouldn't do is put a comment that says what the actual instruction is doing i.e.

mov ah,2  ;move 2 into ah register

This comment is useless & totally unecessary, hope this helps to put you on the right track :U

[gammaman]

Thanks, but I understand what comments are used for.  If you read my earlier posts, I explained that my assignment was to comment a program given to me.  Problem is that the course is on computer architecture not assembler.  I do not know assembler, nor do I have time to learn it in a 3 week summer class.  So what I am asking is based on what research I have done, and based on help from others in this forum, do my comments reflect a correct understanding of what the code is doing.  Our prof wants us to comment the code to show that we understand assembler as it pertains to computer architecture.

[dedndave]

the one i commented is a good example
i modified the program because it was sooooo sloppy - lol
but, all i did was put the repeated instructions into a loop
so - use the comments from mine, and apply them to yours, less the loop

[Mark Jones]

Matt, it seems like you are in a paradox: you don't want to (or can't) learn the assembler, but the instructor is pretty much expecting this of you. I mean, how else are you supposed to comment code unless you fully understand it?

I think the bottom line here is, if you really want to comment effectively (regardless of your "comment skill" and background), you must learn the material. I too am entrenched in the bunkers of college life, and when the instructor asks exceptional things, then only the exceptional students produce exceptional results.

That said, perhaps what would help is some definitions. Download the MASM32 package and see \masm32\help\opcodes.chm for each of those instructions. This will at least give you some idea what each one is doing. However there is no way around it, you're going to have to do some studying and research on your own time to nail this.

(Well, you could probably buy an answer at RentaCoder.com, but then you'd only be cheating yourself.) :bg