HomeForumsWhat's newResources 
 
 
Good Code Commenting
slobu - Aug 22, 2011
  slobu Aug 22, 2011
How does one comment their main program and functions? I've heard good coders have default templates to help them describe their programs and functions. As I am forced to rewrite my engine I've come up with these examples below. How do you (more savvy) coders comment your code? Is this overkill or just right?

Code: 
  
 ' PROGRAM NAME:

 ' SpelunkKingR3_0000.bex (Spelunk King Third Engine Rewrite)

 ' Filename convention is Game Name + Engine Revision + Build

 ' 

 ' DESCRIPTION:

 ' First builds worked off of 22x22 tile chunk scrolling/map loading strategy.

 ' Second build focused on using 16x16 map chunks and using 64x64 tile collision map.

 ' This build will resize collision map entries to player sprite size (16x16 pixels)

 ' Also will feature integration of 16x16 tile map chunk scrolling/loading.

 '

 ' BUILD SETTINGS:

 ' Assumes [X] Make All Variables in Subs/Functions Global

 '

 ' STYLE CONVENTIONS:

 ' COMMANDS should be in upppercase.  Labels should be uppercase for first letter in words.

 ' variables should be in all lowercase.

 ' obj_ denotes array for game objects such as players and monsters that have multiple attributes.

 ' spr_ indicates sprite and tile data

 ' pal_ is palette data

 ' Major sections in program get 2 lines of white space and a "** [Section Purpose] **" comment. 

 '

 ' SPECIAL THANKS (No particular order):

 ' The BEX community.  SegaExtreme forums.  Chilly Willy.  Moon.  Elusive.  Damainman69.  DevSter.

Code: 
  
 ' COMMAND NAME:

 ' DRAWBLOCK

 '

 ' DESCRIPTION:

 ' Draw 16x16 pixel object and apply change to collision map

 '

 ' ARGUMENTS:

 ' dbn is the tile to draw and insert into tile buffer

 ' dbx is the horizontal 16x16 pixel block coordinate

 ' dby is the vertical 16x16 pixel block coordinate

  Chilly Willy Aug 23, 2011
I follow the "Real Programmers" philosophy - "Real programmers never comment; if it was hard to write, it should be hard to read, and even harder to change."

 slobu Aug 23, 2011

Chilly Willy said:
I follow the "Real Programmers" philosophy - "Real programmers never comment; if it was hard to write, it should be hard to read, and even harder to change."


I hear that! Back in high school I wrote a platform scrolling engine in QuickBasic. It used Mode 13 (320x200 256 colors) without a buffer. To emulate a buffer I set half the colors black and XORed part of the screen. The scrolling was accomplished by copying a viewports worth of drawn (but blacked out) "tiles" until an updated set of tiles were needed.

Years later I have no idea how I did it - and I have the source

All fun aside I'll assume 2 things from what you said (or didn't say):

* It's always best to keep it simple enough that comments are unneeded and/or redundant.

* No real problem with my comment style.

Thanks again Chilly Willy

 Chilly Willy Aug 23, 2011

slobu said:
I hear that! Back in high school I wrote a platform scrolling engine in QuickBasic. It used Mode 13 (320x200 256 colors) without a buffer. To emulate a buffer I set half the colors black and XORed part of the screen. The scrolling was accomplished by copying a viewports worth of drawn (but blacked out) "tiles" until an updated set of tiles were needed.

Years later I have no idea how I did it - and I have the source




Yeah, that old stuff is sometimes pretty baffling.


  
	
	

		
		

			All fun aside I'll assume 2 things from what you said (or didn't say):



* It's always best to keep it simple enough that comments are unneeded and/or redundant.



* No real problem with my comment style.



Thanks again Chilly Willy


Yeah, it seems okay. Avoid "over-commenting" - I hate code where there's a three page comment for every line. Write a damn book if you want to comment that much!

I mainly give an overview at the start covering things like global variable/register usage (especially for assembly code), and then basic comments where appropriate. If you use decent names for variables and functions, you can avoid tedious comments, like

uint16_t xx10y3t; // this variable holds the number of cycles until the next emulator event

Uh... yeah. So why not just use

uint16_t cyclesUntilEvent;

I've always gone for descriptive names... gives me an excuse not to comment as I'm a lazy bum.