[parisc-linux] Code Readability

[parisc-linux] Code Readability

[Philipp Rumpf]

As there already seems to be a discussion going on about this, here's a list
of things I would change in order to save developers time;  this is obviously
biased towards developers who spent some time doing this, not towards those
new to the code.

 - get rid of the cvs $Log$s.  Not only do they tend to get longer than the
code in question, they also seem to be downright boring to me.  The only
information you need in the common case is "who was the last one to modify
this file" which $Id$ does just fine.

 - use #if 0 (or #ifdef SOMETHING) instead of "/*" to comment out sections of
code more than one line long.

 - try to avoid using C++-style "//" line comments, or any comment style except
the usual one, which is
	line; /* line comment */

/*
 * long comment
 * ...
 */

 - if you use #ifdef SOMETHING_DEBUG to conditionally compile sanity checks,
put an #undef SOMETHING_DEBUG or #define SOMETHING_DEBUG at the top of the
file.  If it is a header file, you don't want to run into problems because
#define SOMETHING_DEBUG is in some .c files and not in others.

 - stay with standard linux names.  We're pretty good at that.

 - look at Documentation/CodingStyle once in a while, especially Chapter 4

	Philipp Rumpf