Commenting your code ...

[James Ladd]

http://particletree.com/features/successful-strategies-for-commenting-your-code

[Randall Hyde]

http://particletree.com/features/successful-strategies-for-commenting-your-code

Well, the good news is that this is a post actually pressing for good comments. I can't believe how "in vogue" it is to claim that you shouldn't comment your code. Stupidist idea I'd ever heard.  Even more so for assembly language  :8)
Cheers,
Randy Hyde

[PBrennick]

Well, the good news is that this is a post actually pressing for good comments. I can't believe how "in vogue" it is to claim that you shouldn't comment your code. Stupidist idea I'd ever heard.  Even more so for assembly language

Very well said, I think I carry it too far, though, or is that possible?  :bg
Paul

[Jeff]

as long as it doesnt interfere with the readability of your code IMO.  :)

[hutch--]

I agree that the current trend to not comment code is a very foolish one. It is easier to do with some high level languages where you have verbose language form that is partially self documenting but it can be done very badly as well and end up like the old horrors that no-one could read.

I don't seriously think that the area can be sensibly made into a formula but I do have some preferences with assembler coding that appear to manage both considerations. Assembler code at the mnemonic level is narrow code that is useful to be able to read it in many instances like a list. The problem is if the list is too long, its hard to maintain continuity while reading it.

Two things fix this situation by a long way, break up the code into logical blocks and comment well off to the side. Use a lower indent with labels and place them on a single line by themselves. Try and divide blocks of code on their natural boundaries like procedures, loop code blocks etc ... Using a proc I needed recently, it looks something like this,

Code Select Expand


; «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««

align 4

loadptrs proc psrc:DWORD,wcnt:DWORD

    LOCAL parr  :DWORD

    push ebx
    push esi
    push edi

    mov eax, wcnt
    add eax, eax
    add eax, eax                        ; eax * 4
    mov parr, alloc(eax)                ; allocate array of pointers for unique words

    mov esi, psrc                       ; source address
    mov edi, parr                       ; pointer array address

    mov [edi], esi                      ; load 1st pointer
    add edi, 4
    sub esi, 1
    mov ebx, 1                          ; add count for 1st pointer

  align 4
  @@:
    add esi, 1
    cmp BYTE PTR [esi], 0               ; test if you are at the next zero seperator
    jne @B
    add esi, 1                          ; get the next address past the ZERO
    mov [edi], esi                      ; store it at locaion in EDI
    add edi, 4                          ; set EDI to next pointer location
    add ebx, 1                          ; increment the pointer count
    cmp ebx, wcnt                       ; test if its equal to the wordcount
    jle @B

    mov eax, parr

    pop edi
    pop esi
    pop ebx

    ret

loadptrs endp

; «««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««


[rea]

Hehe, I have my own words about commenting and documentation and other things that are there... from some time now... tought the little that have read in that article, not take the "problem" like I take it.

[Randall Hyde]

Well, the good news is that this is a post actually pressing for good comments. I can't believe how "in vogue" it is to claim that you shouldn't comment your code. Stupidist idea I'd ever heard.  Even more so for assembly language

Very well said, I think I carry it too far, though, or is that possible?  :bg
Paul

Absolutely. Once the person spends more time trying to figure out what the comments are saying than it would take to figure out the code by reading the code, you've over commented.

For most languages, a comment to lines of code ratio between 4 and 10 is about right (that is, about one comment for every four to ten lines of code). Of course, we're talking about *descriptive* comments here. A row of asterisks or a blank line doesn't count. :-)  Naturally, we're assuming that the comments are well-written and not of the sort like "set EAX to zero".  And, of course, worse than no comments at all are comments that are wrong. People believe comments before they believe code, even when it's obvious that the code doesn't match the comments.
Cheers,
Randy Hyde

[rea]

I like the editors that let me hide comments and documentation (in the case of some languages that let you do this), I read the code directly, I try to mix the function calls, the tree generated and such things, where is the function that call it and things like that for construct in my mind the programm, know a little about the problem and understand how they have taked the problem. If I really dont get it, I go to the comments or documentation.


My idea about the documentation and commentation is about not write them in the code, I have liked the simple idea of betov (dont blame me for this) about "a code editor is a code editor and not a text editor" something like that..., then when you are writing programm you use a code editor, when you write comments you use a comment editor and objetives of the program and other "ingeniering things" like TODO, ERROR, FIND and a lot of others marks, when you write documentation you use documentation tools and not need learn a new language for this (even more wysiwig or something like LyX) and yes, they should interact one with the other... also with a control version system.

Fo0der have argee about the flexibility that grep give in the case for search of "TODO" and things like that... but will more nice than instead of think in find some short of string in the source, when you open the project, you get the lists and such things...




There are other things for consider, but I guess should be good some like that.



And yes, like some one said before, that will lead to depend in the tools, there is when some standar need be shared, in that way, dosent matter that a tool is propietary or free, because the standar is free.


If some things are "evolutioning" why not this?