I have written an ATA-7 IDE library and I didn't think it was going to get too big but now I have over ~5000 lines of codes and documentation for the code. I always comment every single line of my Assembly Codes but commenting ~3000 lines of code is easier said than done. I just wanted to ask for ideas how people prefer to read the comments? Should every single line of the code be commented? Should a block of code have comments or ...?
Posted on 2007-06-02 04:33:17 by XCHG
surely not every single line.

I preferer commenting "blocks" of code, and commenting instruction whenever needed. Something like this:

;eax = 8*x + y
mov eax,
shl eax, 3        ;*8
add eax,


commenting things like "mov eax," is usually completelly useless and makes reading of code even harder sometimes :)
Posted on 2007-06-02 04:45:17 by vid
Additionally:

1. add a (global) header to each file explaininhg what happens and list all procs like an index and if necessary all libs/incs/macs etc that your libs depends on.

2. add a (local) header to each proc or macro which list all required input (on stack, in registers,..) and what values are returned and where one can find them (again stack, registers,...), especially with macros you might want to add a list of registers which content is destroyed after the macro has been used.
Posted on 2007-06-02 06:46:12 by atcl
I agree with vid: comment blocks of code - and for functions, describe what input/output it takes and what it does, perhaps which algorithms it uses, etc.

Per-line commenting is silly, unless you're doing tricky optimizations.
Posted on 2007-06-02 06:46:55 by f0dder
Yeah I thought so, too. I normally comments blocks of codes for myself so that when I return to it later I will remember what I have done and why. About documentations for procedures/functions, I document them like "holy potatoes" (TM). For instance, attached to this thread is the documentation that I have written for my [__IDEReadFromPortsLBA28] function that reads sectors in PIO from an IDE drive.

Alrighty then I think I am going to stick to commenting blocks of codes rather than each line. Thank you guys.
Attachments:
Posted on 2007-06-02 08:34:21 by XCHG