Back to General and Gameplay Programming

Commenting Style

caseyd · 2006-04-01T21:02:02

I'm interested in hearing about how everyone else comments their code. I personally put a comment at the top of each file describing what it is, and if it's a class definition, I describe what the class is used for. Above any functions I place: /* ==================== function name notes ==================== */ I usually only put comments in methods if there is something going on that may not be obvious. I also add little one liners at the end of a class definition or if I have nested control loops, at the end of each larger block. Just curious as to what other people do.

General and Gameplay Programming Programming

Started by caseyd March 28, 2006 07:22 PM

50 comments, last by gregs 18 years ago

OrangyTang

1,298

March 29, 2006 12:42 PM

Quote:Original post by owl
Quote:Original post by OrangyTang
Quote:Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.
[rolleyes]

what if you had a function like this:

What about it (other than proving that C++ has a somewhat verbose and ugly syntax)? If you want to improve it then a typedef for the return type would help a good amount. If you're still not satisfied then I'd suggest a better syntax highlighter than this forum's. Changing the colour of all brackets can help considerably.

[size="1"][[size="1"]TriangularPixels.com[size="1"]] [[size="1"]Rescue Squad[size="1"]] [[size="1"]Snowman Village[size="1"]] [[size="1"]Growth Spurt[size="1"]]

slowmike

144

March 29, 2006 12:45 PM

Quote:Original post by OrangyTang
Quote:Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.

I think the point is so that when you are scrolling your code, you can see which function you're looking at and what its purpose is without ever having to look at the actual code (comments only). Also, it confirms which function you're talking about. Though most people would put such a comment above a function, they could put it below. I guess it's a matter of personal preference.

owl

376

March 29, 2006 12:48 PM

Quote:Original post by OrangyTang
Quote:Original post by owl
Quote:Original post by OrangyTang
Quote:Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.
[rolleyes]

what if you had a function like this:

What about it (other than proving that C++ has a somewhat verbose and ugly syntax)? If you want to improve it then a typedef for the return type would help a good amount. If you're still not satisfied then I'd suggest a better syntax highlighter than this forum's. Changing the colour of all brackets can help considerably.

Yeah. It happens that you may want to make a brief resume of what the function is all about. The comment may be not so brief sometimes, and it's nice to see the function name heading it.

But it's a matter of personal preference.

[size="2"]I like the Walrus best.

Floating

122

March 29, 2006 08:25 PM

Quote:Original post by supagu
using /* */ is evil!

a true story:
one day i was getting a crash in the SDL library, so i d'led the source, compiled it and got it working, with the crash still.

So i had to find the bug, which could have been any where, so the only way to isolate the problem was to comment out blocks of code.

now when every line, and every function has a /* */ style comment, and you want to use do do a /* */ to comment out slabs of code, your life becomes hell! it took me many hours to remove thier comments.

Eventually found the problem and vouewd only to use /* */ for commenting out blocks temporary!

Same here. And what I do quite often with code blocks that need to be commented in/out often:

/*
code...
//*/

By doing so I don't need to add/remove the closing */ at the end. That is particularly useful when the code block to be commented out is long.

_Sigma

792

March 29, 2006 09:03 PM

Quote:Original post by Konfusius
I use doxygen, but Natural Docs looks sweet, too.

Has anyone used this yet? This looks fantastic!

Boder

935

March 29, 2006 09:11 PM

Natural Docs have really impressed me.

Check out the Photon Documentation

johnhattan

2,354

March 29, 2006 09:18 PM

Quote:Original post by izhbq412
Many of my comments are several lines long, explaining the principle behind the code. I used to write a header of comments above the implementation of every function, but as I got more experienced I discovered that most of the funcions were self-explanatory and no comments were necessary. So now I just put a line of //----------... between the implementations, and the comments, if any, go in the header file.

I also use the // TODO: and // HACKHACK: prefixes.

Writing a brief comment above an unusual piece of code goes without saying.

Instead of TODO, I use my initials (JJH). They have the advantage of appearing in no English words, so it's easy to search.

Oh, and I use only inline comments. /* comments */ are only for temporarily commenting out blocks of code.

(my byline from the Gamedev Collection series, which I co-edited) John Hattan has been working steadily in the casual game-space since the TRS-80 days and professionally since 1990. After seeing his small-format games turned down for what turned out to be Tandy's last PC release, he took them independent, eventually releasing them as several discount game-packs through a couple of publishers. The packs are actually still available on store-shelves, although you'll need a keen eye to find them nowadays. He continues to work in the casual game-space as an independent developer, largely working on games in Flash for his website, The Code Zone (www.thecodezone.com). His current scheme is to distribute his games virally on various web-portals and widget platforms. In addition, John writes weekly product reviews and blogs (over ten years old) for www.gamedev.net from his home office where he lives with his wife and daughter in their home in the woods near Lake Grapevine in Texas.

TrueTom

110

March 30, 2006 02:50 AM

If you are using Doxygen and you want better output, you should give DoxyS a try...

Anonymous

March 30, 2006 06:57 AM

Quote:Original post by Rob Loach
I use XML In-Code Documentation.

I don't really understand why anyone would want to use a commenting style that is as bloated as XML. Javadoc, Doxygen, Natural Docs etc. generate comments using a much simpler notation which is readable even without passing it through a parser. This seems like a clear advantage to me. Could someone who likes XML comments explain to me: Why?

benryves

2,001

March 30, 2006 08:17 AM

Quote:Original post by johnhattan
Quote:Original post by izhbq412
Many of my comments are several lines long, explaining the principle behind the code. I used to write a header of comments above the implementation of every function, but as I got more experienced I discovered that most of the funcions were self-explanatory and no comments were necessary. So now I just put a line of //----------... between the implementations, and the comments, if any, go in the header file.

I also use the // TODO: and // HACKHACK: prefixes.

Writing a brief comment above an unusual piece of code goes without saying.
Instead of TODO, I use my initials (JJH). They have the advantage of appearing in no English words, so it's easy to search.

At least in Visual Studio, anything after //TODO: will appear in the "Task List" tab at the bottom of the IDE, even easier to search [smile]

[Website] [+++ Divide By Cucumber Error. Please Reinstall Universe And Reboot +++]

Commenting Style

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Commenting Style

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Reticulating splines