Summarized Pre-commenting

[DarkAuron]

I got a nice idea (some of you might have already tried this) to add a summarized block of comments before your code to explain what all the code does, in order. Through the summary you could put number and letter labels that share the same label with the code that does what it's describing. This could help in debugging or even going back to the code after a long period of inactive programming. A very simple example:

Code: Select all

-First block of code is simple: [1a] include ion and keypress data, as well as [1b] required headers.
-Start of the loop, we have the [2] square thrown onto the screen at 0,0. Whee.
-Then we do a [3a] direct input check to see if MODE was pressed, if so [3b] exit.
-[4] Loop!
-[5] Square's image data. Simple.


.nolist
#include "ion.inc"             ; [1a] Included files, duh.
#include "keys.inc"
.list
#ifdef TI83P                   ; [1b] Headers and such. m00.
  .org progstart - 2
  .db $BB,$6D
#else
  .org progstart
#endif
  ret
  jr nc, start
  .db "Blah",0

start:

  xor   a                      ; [2] Load coords for 0,0
  ld    l,a
  ld    b,8
  ld    ix,Square
  call  ionPutSprite           ; And put onto the screen!
  call  ionFastCopy

  ld    a,Group7               ; [3a] Check to see if MODE was pressed
  out   (1),a
  in    a,(1)
  cp    kMode
  ret   z                      ; [3b] Exit the program upon hitting CLEAR

  jp    Start                  ; [4] Jump back to the beginning! AGAIN! AGAINN!

.end
END
                               ; [5] Aaaand here's data. Boring data at that.
Square:
.db $FF, $FF, $FF, $FF
.db $FF, $FF, $FF, $FF

Probably not the *most* efficient way to do it, but if you do it enough you might adjust it to work better.

[tr1p1ea]

This is a nice idea. You could write detailed explanations of your code and have more space to do so. Then its just simple referencing.

[DarkAuron]

Glad someone noticed And also it would *really* help with sharing code as well. Someone could read the summary and get the general idea of what things do, and if they need to figure out what you're saying in your comments, they could read your summary at the top. I could have had a better example but I was trying to apply the concept at a simple positioning as to not complicate the idea off the bat.

[kv83]

Isn't that basicly the same idea as Timendus had with his z80 commenting system?

[coelurus]

Isn't this commenting-madness getting a little glorified? Gemini was written in one 6500-line file with comments thrown in here and there explaining what happens and I can still look up specific sections. All the labeling and stuff just takes commenting space and time to make sure the labels are correct If people wanna use your code, explain what it does in an external document and just "mark" the sections in the source file, it's much easier to get an overview that way. And if they can't understand the code flow, I can't see what they're doing with that kind of complex code anyway

[DigiTan]

In this open-source environment, the best commenting will also explain the rationale of it's instructions. Especially if you ever want to have it ported. For example, this is taken directly from Robot War...

Code: Select all

SAVE2:
Save_now:
;                                               ;
; Save and return to titlescreen                ;
;                                               ;
; Using "Save_now" will return you to the       ;
; homescreen                                    ;
;-----------------------------------------------;
 ld hl,save_and_clear
 push hl                        ; Place the lable on the stack for later

SAVE:
;                                               ;
; Basic save.  Call this to save *without*      ;
; returning to the mainscreen                   ;
;-----------------------------------------------;

 ld hl,STORY0
 set 6,(hl)             ; Disable first-time auto-save function

 call RELOC_INSTALL             ; Reinstall Relocation Code

 ld hl,NewVarName               ; HL -> name of samegame variable
 rst 20h                        ; Copies (HL) -> (OP1)
 call _CHKFINDSYM               ; See if the variable exists already...
 inc de                         ; Load Savegame data into text_memory...
 inc de                         ; ...and text_memory2 for later use
                                ; Now DE=address of savegame
 ld hl,TEXT_MEM
 ld bc,SAVE_SIZE1
 ldir
 ld hl,TEXT_MEM2
 ld bc,SAVE_SIZE2
 ldir

 ret                    ; <-- IMPORTANT: This "ret" will send the PC...
                        ; to "save_and_clear" if "SAVE2" was called...
                        ; OR it will return as normal.

...If uncommented or vaguely labeled, a typical porter might see the "pop hl," and arrogantly delete it--and crash the game to their suprise. The commenting prevents this disaster from becoming real. Also, I always go out of my way to explain "exotic" instructions like "rst 20h" and every subroutine.

No RW porter should ever have to turn to a TI82 tutorial or other reference while porting, at least not for anything that conserns an 82. The commenting explains it all.