OSDev.org

Hi !
What code style do you guys prefer ?

uint some_function(type_t *t).....

or

UINT SomeFunction(TYPE *t).....

#include <stdint.h>
uint32_t someFunction( type_t * t )...

I tend not to create my own standards when there are existing ones.

The great thing about standards is there are so many to choose from.
-- Somebody (Andrew T. I think)

I prefer:
uint32 SomeFunction(type *Variable)...

All functions and variables have capitalised names, all types and keywords are all lowercase. It makes sense for me ;D.

yea as above

I prefer(though I use to not and use under lines)
unsigned int SomeFunction(my_type blah_or_whatever)
#define THIS_IS_IT 1

and for 1 use typedefs(very seldom used) now I use structs but anyway
typedef struct{
unsigned int Hello;
unsigned int World;
}BLAH_OR_WHATEVER;


and for popular typedefs
typedef struct{
unsigned int hello_or_blah;
unsigned int and_again;
}the_type;

and sometimes I'll put a _ before it like _the_type;


but anyway....

yayyak wrote: The great thing about standards is there are so many to choose from.
-- Somebody (Andrew T. I think)

Quite correct. But the C lib is at the basis of it all, so it's a rather strong standard for the type of work I do.

My capitalization comes from years of C++ coding. Classes CamelCased, functions (methods) startingWithLowercase(), members being mCamelCased or sCamelCased, other variables lowercase. I stay away from leading underscores, except to mark something as strictly internal. You also have to be careful not to follow up an underscore with a capital letter, as those are reserved symbols. Postfix _t for typedefs and data structs (to distinguish them from classes), UPPERCASE for macros only.

What does "camel case" mean?

lowercase, UPPERCASE, CamelCase. You know, as in camel humps. The stuff Wikis usually autodetect as a Wiki link.

The style described above comes probably more natural for a German than for an anglophone. Classes describe things, which are capitalized (SomeThing). Methods describe actions, which aren't (doSomeThing). Both is the same as in the German language. The uppercase letters mark the start of a new word in the class / function name, making for easier reading.

Variables usually describe things, too, but they're either member variables (where I use 'm' to specify non-static members, and 's' to specify static / class members), or local to the function where they usually get names like 'i' or 'tmp'.

I used to use

camelWithInitialLower for variables and methods/functions
FullCamel for classes
c_PrefixAndCamel for member variables

it's gradually turning into

lower_with_underscores for variables
FullCamel for classes and methods/functions

though this would imply moving to

m_prefix_and_underscores for member variables

which I don't think looks quite right

I thought that thisWasCamelCase and ThisWasPascalCase...

I just call it what makes sense and gets the message across

[tt]Structs[tt],
[tt]StructsWithMultipleWords[/tt],
[tt]Classes[/tt], and
[tt]Typedefs[/tt] in general;

[tt]variables[/tt],
[tt]variables_with_multiple_words[/tt], and
[tt]function_names[/tt], regardless of whether they are members or not.

[tt]DEFINES[/tt]
[tt]MACROS(a,b,c)[/tt]

[tt]leading_space_before (functions)[/tt],
[tt]leading_space_before [brackets][/tt],
[tt]space_around (function) {
braces
}[/tt], with one-tab (not space) indent.

[tt]space + around - (most * operators);[/tt],
[tt](but.not)->all[/tt], especially
[tt]no_space* before_a_pointer_decl (unless, absolutely, necessary)[/tt].

;D

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.

I've not written C/C++ for long time, thought I've some general style guidelines:


@ Do not use unmeaningful names like x y z e i u, use names which are meaningful, long as possible, simple and quick to write. I take numbers from lojban language to fill one letter name's places: no=0 pa=1 re=2 ci=3 vo=4 mu=5 xa=6 ze=7 bi=8 so=9, they can be combined, like: muno would mean 50. I use them usually in axes and such things which are obvious, I don't like one letter names. I use - and _ -letters to combine words, mostly I prefer those which have more than two or three letters. kind-of is not a good name I think. I'm attracted from english names which I didn't earlier knew.

Examples from my good names:
# strong-line
# capability
# superblock
# window-context

@ Different kind of things have different namings.

@ Case matters.

@ The code must be self-commenting, it is not nice to read stupid comments which tells nothing, for that we have good manuals! Only comments which tells something what code can't tell are allowed, and very rare.

@ If I distribute code, I prefer to write short but understandable documentation with little english grammar rules invoked to make it very-clear.

@ It is better to have much spaces and returns than little number in lines of code.

@ Rather localised lines than some boring template pattern which defines where do you write includes or separate classes and functions. There is always a smart order in my code.

Hmmm... I agree with most of your points. A notable exception is the lack of commenting. Commenting is good. I have only come up against two reasons people make a rule like yours (and both are bad):

• You don't know how to comment (that's not an insult, it's a skill like any other that you have to learn).
• Laziness (I suppose technically that one *is* an insult, but everyone's lazy to some extent, me especially).

As an example, comments like:
Is a comment that shouldn't be there at all. 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

There are obviously more cases where commenting is needed, but those are the main three that seem to make code easier to use.

I have only a few rules, but they govern my style pretty well.

- You only include headers in headers if you must. You must include them if your header needs to know the contents or the size of the structure. Passing by reference or by pointer explicitly doesn't qualify.
- Each code file includes all the headers that its headers include as well. Changing any header include logic may not require a change to your code file. Especially after changing code, cleaning up the header shouldn't affect any code file using it.
- There's a sidenote to this, there's an exception to the rule for standards and for include-many headers. You can include any standard file in a header. You can also not include all subfiles from the header but just an include-many header instead, which is a header that includes loads more. This is mainly for using libraries.

- You comment on only interesting stuff:
- You comment on algorithm implementations, one line of comment for each step of the algorithm. You shouldn't have to read the code to retrieve the algorithm.
- You comment above functions or files for all nontrivial assumptions in the function or file. If you assume X, Y or Z, document it. You don't document that you expect an int to be between 0 and 4294967295 on the target system (although this is not good either, but at least it's to be expected), you do document that you can only handle 20 users at a time due to an array. Even if 20 seems far off. If you thought about a limit, write it down.
- You comment on each class and interface what it's responsible for. Not what it is, what it might want or such, just what it's responsible for. That way people maintaining your code know what a class was supposed to do so they can actually assess whether the behaviour detected in the system was because your code didn't do what it should have.
- When during coding you feel something isn't entirely clear for you, or when during testing any bit of code seems to have an above-average amount of errors, note this. It's good to know that when you have a problem in a program you don't know where the problems were found in the past, since it's a pretty good chance that there are problems there or that they were solved with a symptom solve.
- When you notice something, ANYTHING, that needs to be done but you don't have the time to do, add a note. Prefix it with TODO, XXX or FIXME for greppability, but at least add a note. Even for things you think are bloody obvious (such as a missing free) but hard to check/fix. If it was such a strange construction, it should've been documented anyway. Such bug reports may only be replaced by either strange-bit documentation or a fix for the described problem.
- You document the generic flow of the program. Preferably you document the entire design, but just knowing what the generic flow through the program is is quite useful in itself, and a whole lot less work to do.Don't delve into details about how it's set up or how it's linked, just how calls flow and what makes the program do what it does most.

Naming and so on are details. If you get your commenting right you'll have a lot more understandable code right away.

Naming is important though, got a few basic guidelines:

- Stuff that's used for only a single screen (max, that's 25 lines) you can use i until m. If you use them longer, use a longer name so it's clear at the end what it was doing at the start.
- Classes all use CamelCase with a capital letter. Structs are equal.
- Functions start with a lowercase letter.
- Member variables start with an underscore

For the rest, use common sense.

[edit] Note to self, don't leave edit window open for hours. [/edit]