Code Commenting Conventions

[xyzzy]

Recently, I have discovered Doxygen, though, so I am starting to go through my code adding comments to let Doxygen generate documentation. If my kernel gets really big, this should be a good timesaver later.

I've also started using Doxygen comments in my code. It's very helpful to be able to see instantly what a function does, exactly how it behaves, etc, just by looking at the comment. I also try to comment the internals of functions well if there is anything non-obvious. I don't swear particularly much, only if something like GCC annoys me. I sometimes make jokes in the comments too, although certainly not as much as I used to. I remember getting bored ages ago and writing a comment saying what will happen if the kernel gets to a certain point that it shouldn't, complete with an ASCII-art drawing of a box labelled "Kernel" flying into a brick wall

[lukem95]

"complete with an ASCII-art drawing of a box labelled "Kernel" flying into a brick wall

completely necessary of course

[niteice]

I still think this inverse square root algorithm from Quake 3 has the best progression of comments (of course, uncensored):

Code: Select all

float Q_rsqrt(float number)
{
	long i;
	float x2, y;
	const float threehalfs = 1.5F;

	x2 = number * 0.5F;
	y  = number;
	i  = * (long *) & y;						// evil floating point bit level hacking
	i  = 0x5f3759df - (i >> 1);                 // what the ****?
	y  = * (float *) & i;
	y  = y * (threehalfs - (x2 * y * y));       // 1st iteration

#ifdef __linux__
	assert(!isnan(y));   // bk010122 - FPE?
#endif
	return y;
}