Good Code Commenting

[slobu]

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?

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

 ' 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]

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]

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]

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.