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?

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:



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.

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.

I only comment on above my functions. I dont comment on its contents. It makes my code messy and sometimes unreadable.

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:

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 , 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!

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:

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.

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?

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).

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.

somebody understand linux sources?
The important is that at least the maintainer of the code could understand it.

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?

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).

Nice article, not only about programming. I will try to follow author's suggestions and will see if somthing will improve in my life