flat assembler
Message board for the users of flat assembler.
![]() |
Do you comment your code very well? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Total Votes : 20 |
Author |
|
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.?
|
|||
![]() |
|
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. |
|||
![]() |
|
tom tobias
Quote:
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. ![]() |
|||
![]() |
|
estrang
I only comment on above my functions. I dont comment on its contents. It makes my code messy and sometimes unreadable.
|
|||
![]() |
|
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 ![]() P.S: Yay for random rants! P.P.S: Yay for P.S! |
|||
![]() |
|
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] |
|||
![]() |
|
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.
![]() 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). |
|||
![]() |
|
Octavio
rugxulo wrote: I personally don't comment enough. 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. |
|||
![]() |
|
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? |
|||
![]() |
|
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). ![]() |
|||
![]() |
|
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
![]() |
|||
![]() |
|
< Last Thread | Next Thread > |
Forum Rules:
|
Copyright © 1999-2019, Tomasz Grysztar.
Powered by rwasa.