On Commenting...

[Alboin]

Hello,

I was just wondering how people here comment their code. Do you have a system? A header at the top of each function\file, or do you simply comment when the need appears? Moreover, what do you consider to be a good commenting style?

Thanks,
Alboin

[Combuster]

Depending on the kind and size of the project, I add more or less comments. I'm pretty thorough when commenting assembly though: my kernel. The convention I use is mainly because of the documentation generator I use in conjunction with my OS (good for managing some 700 files). It also prevents me from going nuts from trying to remember the definitions and specifications of all functions.

Outside my kernel, when its a serious project I do attach specifications to functions, but usually things are limited to code semantics and function-level design choices. But then again, the next largest project I worked on only featured some 50 files, so in essence I really document based on need (that includes college assignments ).

Independent of what is commented, some consistence is a pre.

[Telgin]

My commenting style is a bit of a hodgepodge actually.

During my college courses, I got into the habit of puting a header in each file describing the general content of the file and its purpose, author and creation date. I still do that, even for hobby programs that no one else would ever see.

As for the rest of my program, I used to comment almost every block of code. This was generally comprised of bad comment style: I just restated what the code did in English. Since most people seem to think that's bad, I've recently tried to get into the habit of just putting useful comments, generally ones that would remind me of what the code did later on if I looked at the file again. Some things are obvious, but others aren't.

I used to not put a comment header for functions, especially ones that were too simple to comment. Lately though I've tried to get into the habit of doing it anyway, since certain things like return codes and parameter expectations can be useful.

[piranha]

I comment at the end of each "release", because I can remember what I write, and if someone else wants to read my code then thats they're problem. They must figure it out them selfs. HAHAHAHAHA!!!! And.....you know...Why do they even WANT to read my code? It's difficult to read, and pointless because they wont learn anything useful. Plus, why not just look at code thats successful? OK?! About 1 person actually knows my code (me). Look at Linux or something? Jeez. OK, I'm done.

Don't......even try to understand the cause of the above rant. I'm generally annoyed.

But......you know, this is actually somewhat on-topic.
Generally I comment like:
/* Alright, so I don't really understand WHY we need to do a bunch of pointless init stuff, why can't someone design a computer that does things logically and somewhat in reality. Or it can just do things for me...Wheeee.*/

-JL

[XCHG]

I used to comment like CRAZY! I mean every single phreaking line was commented like this:

Code: Select all

MOV     EAX , EDX        ; EAX holds the Base Address 15:0 of the TSS  ...
SHL     EAX , 0x00000010 ; Now get the Base Address 15:0 in the High O ...
OR      EAX , 0x00000067 ; Set the Segment Limit 15:0 of the TSS segme ...
MOV     ECX , EDX        ; ECX holds the Base Address 31:0 of the TSS  ...
SHR     ECX , 0x00000010 ; Get the Base Address 23:16 of the TSS segme ...
AND     EDX , 0xFF000000 ; EDX holds the Base Address 31:24 of the TSS ...
OR      ECX , EDX        ; Mix the EDX with the content of the ECX. EC ...

But then one day a light became brighter I realized that it was a waste of time so now I just comment the parts that are tricky and I know I will forget about that trick soon. So I just write comments about WHAT I AM DOING THERE and not what might appear to be going on. I also keep track of every register change. For example, if I change EBX to something at one point, I will keep logging it throughout the code so whenever I see EBX somewhere in the code, if I look a few lines up I will see what the value of EBX is expected to be at that point.

After quitting on commenting every single line, I started writing heavy documentations. If my code is working, then whenever I want to use it, I will just look at the documentations. The ones that I'm writing for Vandior are pretty much as complete as MSDN documentations.

[xyzzy]

I try to add comments to everything that (to me) is non-trivial. Of course, some people would have a different idea about what is trivial and what is not to me.

[JamesM]

I add comments to every header file, and every C file (at work, because we also have to put a copyright notice in there).

I also comment every function declaration in header files. I use the
/**
...
*/
style comment so that doxygen can pick it up automagically and create some nifty documentation for me.

For one liners I just use the standard // comment, and try to comment things which are either abnormal or tricky.

[earlz]

I usually add a comment on what classes are used for, what each class function is(unless obvious, like GetSize() or something like that) and
i add comments in code where things can be tricky and hard to understand...

other than that, I sometimes put comments at places where I made a stupid mistake and tell other programmers to watch and makesure not to do the same...

and in assembly, I add comments before each gosub/function telling what the arguments and such are...

And aside from that, for copyrighted projects, I add a copyright header thing(really not a copyright, just a notification it's under BSD liscense) to each file..

[neon]

I use different comment styles for different purposes.

I always put a header comment at the top of every file, including copyright notice, in a fashion like this:

Code: Select all

/***********************************
 info here
***********************************/

Asterisks are used here as they are more easily seen then alot of other characters.

All routines, structs, and classes use a header comment like this:

Code: Select all

/*
===========================
 info here
===========================
*/

In separating large partions of a source file (Such as a large list of declarations from a list of different classes), I use a special variant of the above comment, like this:

Code: Select all

/*
===========================

       SECTION NAME

===========================
*/

The size of this header block makes it more easier to see and identify.

All comments within the actual source use either /* */ or // style commenting depending on the need. I usually comment to specify what the code is doing, or to make things clearer within more complex code.

If the code itself is fairly readable by itself, a comment is unnecessary.

I almost always use the same basic setup in alot of different languages.

[Solar]

A comment header for every file, holding $Id$ (for version control), copyright / license notice, and a short description of what's done here.

A comment per function in header files, detailing what the function does, what the parameters are, what to expect in return codes (and, if C++, exceptions). The trickier member variables get a comment, too.

In the code itself, I add comments at major control-flow nodes - what's done in this loop, which branch of the if - else does what etc.. This allows me to quickly scan through the code to find a certain code point of interest ("this bug happens in the memory list handling, now where is that...").

More comments are added at tricky code constructs, or when I fix a not-too-obvious bug ("you might think this should start at 0, but it actually starts at 2. See bug #1234...").

Some of this you can see in effect in the PDCLib source (linked from my signature). I have to admit, though, that some parts of PDCLib are much less well-commented as they should be - a pre-alpha symptom that will be fixed for 1.0. (Yes, I consider missing / faulty comments to be a bug.)

[pcmattman]

I usually put a header comment at the top of every file with a basic idea of what the file is for, the date of creation and the author.

I also have a personal preference of commenting as much as possible - I'm not sure why, it just doesn't feel right when code isn't commented. That said, I do sometimes have implementations of functions or algorithms without comments.

[mathematician]

Hello,

I was just wondering how people here comment their code. Do you have a system? A header at the top of each function\file, or do you simply comment when the need appears? Moreover, what do you consider to be a good commenting style?

Thanks,
Alboin

In assembler almost every line is commented. In C I hardly bother at all. Commenting assembler can be a good way to find bugs; as I am about to decribe what a particular line of code is supposed to do I can find myself thinking, "Wait a minute; that isn't right."