flat assembler
Message board for the users of flat assembler.

Index > Heap > Code Comments


Do you comment your code very well?
Yes, I write pseudo-code before I even begin.
0%
 0%  [ 0 ]
Yes, I document every function and header file.
5%
 5%  [ 1 ]
Yes, but I only explain confusing things.
30%
 30%  [ 6 ]
Yes, but I only describe the algorithms.
5%
 5%  [ 1 ]
No, I don't have time, too busy.
5%
 5%  [ 1 ]
No, I let my function/variable names speak for me.
5%
 5%  [ 1 ]
No, I believe you should be able to read code like English.
30%
 30%  [ 6 ]
Well, I do comment but not nearly as well as I should.
20%
 20%  [ 4 ]
Total Votes : 20

Author
Thread Post new topic Reply to topic
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
I read a LONG nine-page thread on some other forum about commenting code and how different people feel it should (or shouldn't) be done. Anybody want to share why/how/etc.?
Post 06 Nov 2005, 04:05
View user's profile Send private message Visit poster's website Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
rugxulo wrote:
I read a LONG nine-page thread on some other forum about commenting code and how different people feel it should (or shouldn't) be done. Anybody want to share why/how/etc.?

Two schools of thought:
1. get the code out the door as quickly as possible.
2. Revise the revision to the redone re-approval of the re-reviewed specifications.
These are two extremes.
The first writes incomprehensible code. Sometimes, a year later, even the author can not recognize his handiwork for lack of commentary.
The second type procrastinates forever, never getting anything accomplished, just revising the revision of the rewritten specifications, and never actually generating any useful code.
Both extremes represent ineffective, and inefficient means of concluding an assembly language project.
Well written PROGRAMS, as opposed to CODE, are eminently readable, with a revision history, so that ANYONE can read and understand what the programmer seeks to accomplish: both why, and how, specific instructions are employed to accomplish particular goals. MOST MEMBERS of this forum DO NOT write such programs. This forum emphasizes CODE, not programs. The forum has been around for a couple of years now, so it should be interesting to go back and review some of the CODE written two or three years ago, and compare it with code written yesterday:
Are the variables ALL defined prior to use, or does the author just drop some undefined variable into the code as he moves along?
Are the instructions MINIMIZED, to ensure readability, or does the author prefer to employ obtuse instructions, with little or no obvious connection to the data processing challenge?
Are data structures developed--do they facilitate comprehension?
Good programming demands the same skills as writing good novels: one needs to go back and reread Anna Karenina by Tolstoy to understand this point. What else do you have to accomplish on a Sunday, anyway? Smile
Post 06 Nov 2005, 17:47
View user's profile Send private message Reply with quote
decard



Joined: 11 Sep 2003
Posts: 1095
Location: Poland
decard
For me it is enough to write descriptive labels in my code, then I usually have no problems with modifing it after a few months. But there are some situations where I always put some comments, like in following sequence:

Code:
        invoke  SendMessage, [.aedit],AEM_GETLINELENGTH,0,0
        push    eax

        (a fef lines of code here)

        pop     eax   ; pop max line length        
    


However situation is different when I have to deal with someone else's code, for example now I'm implementing new asmedit control in Fresh. I had a lot of trouble with this, because I worked with not my code that was almost without comments and documentation. It still don't work well (crashes sometimes). I would surely finished this task if code was better documented.
Post 06 Nov 2005, 18:43
View user's profile Send private message Visit poster's website Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
Quote:

I would surely finished this task if code was better documented.

Exactly!
NOTE for those non-native English users:
Decard's English is PERFECT, though it may have some minor, IRRELEVANT grammatical or spelling errors, HE COMMUNICATES!!!
That is really the message here, on this question of documentation. It does not require 9 pages of discussion, but it IS IMPORTANT, and every program, no matter how small, should have an opening couple of sentences to explain what is going on, in particular, to focus on PROGRAM FLOW, when there are several modules, including external variables.....
Assembly language programs can be elegant, but the precondition for arrival at a readable state, is that such programs must not remain as CODE, interpretable and understandable only by the author.
It is genuinely NOT THAT DIFFICULT to introduce a few lines of text, explaining what one is doing, and why, and how.
In the process of undertaking such an explanation, AT THE OUTSET, instead of commencing with "coding", ONE WILL DISCOVER, with GREAT pleasure, that one has actually IMPROVED on the underlying (and often UNWRITTEN) algorithm.
Some people I know, BEGIN any project by writing C code, then examining the output from the compiler, presenting that output to the world at large as if it represented their own assembly language programming.
This of course is both completely stupid, and utterly dishonest. It is quite simply FRAUD.
BEGIN with an explanation of what you hope to accomplish. Need not worry about grammar, spelling, punctuation--all useless.
FOCUS on the CONTENT. on the IDEA. ON THE ALGORITHM and DATA STRUCTURES. Then introduce the code AFTER the project has been properly defined. Something like FRESH will not only be more easily accomplished (with a team of programmers working on different sections), it will be MUCH easier to modify existing code in the future, INSTEAD OF HAVING TO JUST THROW IT ALL AWAY, as unreadable nonsense. Smile
Post 06 Nov 2005, 22:29
View user's profile Send private message Reply with quote
estrang



Joined: 02 Nov 2005
Posts: 38
estrang
I only comment on above my functions. I dont comment on its contents. It makes my code messy and sometimes unreadable.
Post 06 Nov 2005, 22:35
View user's profile Send private message Reply with quote
gunblade



Joined: 19 Feb 2004
Posts: 209
gunblade
If I'm coding something for myself, which i usually am, then i put barely any comments, the only things would be TODO reminders, or something like:
Code:
;ax = A :: bx = A^B    

just to remind me whats in each register/stack.

Im able to read the code, so i dont see a reason to comment it. Even if i leave it be, and take it out of my mind, i just read over it once and it comes back. Although i do usually make a plan/pseudocode beforehand in another file, if its a big project, then use labels to cut up the code into chunks.

Hehe, that reminds me, had an assignment for university today, writing a hangman program in Ada95, and used about 5 goto's Twisted Evil, I dont know why most HLL users hate goto's/jumps that much. Its more efficient than large nested loops, if not the same efficiency, as for/while loops are just goto's with some kind of parameter checking or counter, and (for me at least) jumps are more readable.


P.S: Yay for random rants!
P.P.S: Yay for P.S!
Post 07 Nov 2005, 10:47
View user's profile Send private message Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7106
Location: Slovakia
vid
i comment each "block" of code, so it is enough for user to read comments, he knows what each block does. i also comment some unclear parts with right-side comment. like this:
Code:
;allocate memory
push dword 0 ;GMEM_FIXED
push [size]
call [GlobalAlloc]    
Post 07 Nov 2005, 13:46
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
I personally don't comment enough. I put a "change list" at the top of the file, as well as mention what OS, assembler, etc. versions I'm using. I version number every file, put a date/time stamp, and mention my e-mail address. I also mention bugs that I haven't fixed and possible things "to do" in the future. I don't comment most functions except if certain things are affected by it (variables, registers). Really, I need to fix that. Razz

Also, any right-hand comments I start at column 40, and I try never to go past column 78 or so. Blank lines help a lot, too, especially around new additions that I may modify soon. I use descriptive variable and label names (if possible), and use lots of equates.

It's kinda endless, you know? Who knows what someone else will understand. Another big problem is that if someone doesn't like your style, they just won't even bother. Besides, the language problem...when will we ever learn? Sad

N.B. http://sed.sourceforge.net has some scripts to remove nested C comments and HTML comments. Not suggested except in extreme circumstances (e.g, trying to compile from floppy boot disk).
Post 07 Nov 2005, 22:42
View user's profile Send private message Visit poster's website Reply with quote
Octavio



Joined: 21 Jun 2003
Posts: 366
Location: Spain
Octavio
rugxulo wrote:
I personally don't comment enough.
me too. Sometimes i just put a comment before the routine about how to use the code,parameters,return value ...
I also put comments when i do strange things like variable code.
Comenting everything is too expensive ,and still there will be a lot of people that will not understand anything, also i think that assembly language is more self-explanatory than other languages.
Quote:
Who knows what someone else will understand.

somebody understand linux sources?
The important is that at least the maintainer of the code could understand it.
Post 09 Nov 2005, 09:04
View user's profile Send private message Visit poster's website Reply with quote
Jaques



Joined: 07 Jun 2004
Posts: 79
Location: Everywhere
Jaques
code should already be in modules and at least as long a module is contained and works it should be left alone. Everything in parts. If they stop working either find the problem or else give up and start over. Code speaks for itself, if you cant read it you maght as well go off and use BASIC.

PS Rugxulo... cxu estas via nomo parolanta tio estas komunisto?
Post 14 Nov 2005, 00:54
View user's profile Send private message Reply with quote
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
Documentation, online help, comments: all necessary for worthwhile programs, but we're all too busy. Here's a page on how not to procrastinate.

P.S. La vera rughulo estas plush-hundeto (kiu similas aspekte al unu el chi tiuj) donacita al mi unu fojon (je la 14-a de Februaro, antau kvar jaroj) de nia kara panjo. Polvighite pro multaj shercoj kaj ludoj ghi nuntempe apartenas al mia frato. Ankau mi nomigis sin chi tiel char la kantoj de Sammy Hagar plachas al mi (vidu lian retpaghon). Smile
Post 14 Nov 2005, 20:56
View user's profile Send private message Visit poster's website Reply with quote
decard



Joined: 11 Sep 2003
Posts: 1095
Location: Poland
decard
Nice article, not only about programming. I will try to follow author's suggestions and will see if somthing will improve in my life Smile
Post 14 Nov 2005, 21:34
View user's profile Send private message Visit poster's website Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You can attach files in this forum
You can download files in this forum


Copyright © 1999-2019, Tomasz Grysztar.

Powered by rwasa.