OSDev.org

Kemp wrote:Proper comments usually are of the following form:

• A description of what is to be achieved by a particularily complicated code block (not a step-by-step analysis)
• Notes on caveats/potential error cases in a piece of code (especially if they are not required to be handled)
• Reason for choosing a particular algorithm, or notes on how your method differs from the norm. For instance a sorting algorithm that has been optimised for the type of data you know it will be working on may confuse someone because it appears superficially similar to the standard algorithm when they first look at it

Those are just the rare comments I described, but very good comments. :) They answers thought questions what code doesn't in itself answer, doesn't they?

Yup Just checking you thought they were good. I've seen far too many people who are told to comment their code, so they do ones that are just essentially the code translated into english, so they're told that they need to comment it better, so they add even more comments in the same manner (including such as the "increment i" comment). Then when they're told their comments still aren't any good they decide commenting sucks and only leads to annoyance.

Kemp wrote: Ah there's a few points I missed. I have space around almost all operators (spacing things out almost always looks nicer), but not when accessing a member variable via a->pointer. Macro names all uppercase as per almost everyone. As for pointer declarations, I have the asterisk attached to the variable name, not the variable type.

int *a, *b, *c;

Rather than

int* a, * b, * c;

(Which I think looks silly). It also helped when I was starting out as in the latter the asterisk looks like it's part of the first word (my internal parser is quite greedy) so it would be tempting by mistake to write

int* a, b, c;

To try to make them all int pointers.

Personally, I would write:

int* a;
int* b;
int* c;

both because I prefer to emphasize the type over the syntax of the expression and because I've never been a big fan of declaring multiple variables per line, even when there isn't as much potential for error as there is with the bizarre pointer declaration syntax. I've never found the whole "*a is an int" thing or "declare it how you use it" thing to be a good reason for visually associating the * with the a, when the type of a really is int*.

Personally, I think I've been bitten by the "int* a, b;" construct far more rarely than I've been bitten by using = instead of == (and that one doesn't happen very often at all).

As for the main question, I tend to stick with something very similar to Solar's, though I generally omit the _t suffix from typedefs, since I've never found it especially useful.

I generally avoid underscores in my names at all costs, except in two very specific circumstances:

1. macro names - since they're in all caps, you need something to separate the words

2. scope prefixes, such as g_ for globals, when I choose to use them, though I don't really see a problem with the gCamelCase style, either

(incidentally, I believe Colonel Kernel is right: thisIsCamelCase and ThisIsPascalCase).

Kemp wrote: ...the code translated into english...they add even more comments in the same manner...their comments still aren't any good they decide commenting sucks and only leads to annoyance.

;D Been there, done that. Then somebody in IRC told me what kind of comments are useful and which aren't.