Xref:	news-dnh.mv.net comp.os.msdos.djgpp:387
Path:	news-dnh.mv.net!mv!news.sprintlink.net!simtel!harbinger.cc.monash.edu.au!barney.eng.monash.edu.au!junaid
From:	junaid AT barney DOT eng DOT monash DOT edu DOT au (Junaid A. Walker)
Newsgroups:	comp.os.msdos.djgpp
Subject:	CODING STANDARDS: A GUIDE
Date:	14 Jun 1995 10:06:41 GMT
Organization:	Monash University
Lines:	205
Nntp-Posting-Host:	barney.eng.monash.edu.au
To:	djgpp AT sun DOT soe DOT clarkson DOT edu
Dj-Gateway:	from newsgroup comp.os.msdos.djgpp

	Well, having started this thread, may we finnish it on a
productive and illuminating note.
	This is from the vsta OS project (GPL'ed 386 multitasking
OS  ftp: src.doc.ic.ac.uk/computing/gnu/cygnus/embedded/vsta).
	I must admit i was pleasantly supprised by the directness
and clarity of this document. It reinforced many of my own personal
preferences on codeing style, and taught me a few to boot!
Also there is a few other documents that are worth reading on the
Usenet; cstyle.txt and one other that escapes memory. I feel that
reading these documents will save many hours of frustrating 
coding (and well real men dont need debuggers!).
	Sorry about the \r's, but if you are just going to have
a skim over this, then dont bother. After all we're going to
archive this on our pc's, arent we....ahh ....

Junaid (be sure to check out the fixed gdb for V2, and i'm sure its
	equally applicable to V1.12m3)







The coding standards for VSTa.

Yes, we have coding standards.  The ones described here apply to
the kernel, C library, utility library, and "core servers"--the ones
you will generally use to boot.  A seperate coding standard
exists for the windowing system.  If another distinct subsystem
comes up, and you write it from scratch, then you can apply your
own coding standard to that part.

I've tried to hone it down to just 10 rules.  It seems like a lot,
but hopefully 5 of them will match your personal style anyway,
so it isn't as bad as it looks.

In case you're wondering, this wasn't my C style of choice either.
But I learned it at HP for their kernel, and had it heavily
reinforced at Sequent with their kernel gurus.  So now I stick with
it, accepting Henry's observation that "standard is better than
better", at least for C styles.

0. Henry Spencer's Rules of C

	Read this article.  Believe it.  The rest of this is just
some refinement of what he says.  This doesn't count as one of the
10, because you shouldn't be writing C until you have read this.
I have included it as "ten.doc" in the root of the distribution.

1. Comments

/*
 * function_name()
 *	One-liner (only) for the function
 *
 * Further discussion.  This is a good place to mention success/failure
 * values and so forth.
 *
 * A distinct thought, or perhaps a note about assumptions or limitations.
 */
struct foobar *
function_name(void)
{
	int x;

	/*
	 * Describe a block of code, then write the block of code
	 */
	for (x = 0; x < FOOBLAT; ++x) {
		something(x);
		...
	}
}

Do NOT use pretty blocks of stars.  They make it hard to update
the comments.  We all know what happens when comments are a pain
to update....

2. Conditionals

	if (condition) {
		...
	}

	if (condition1 || condition2) {
	} else {
	}

	if (foo && !bar) {
	} else if (bletch) {
	}

3. Loops

	for (x = 0; x < 20; ++x) {
	}

Do NOT use the open version:
	for (x = 0; x < 20; ++x)
		bar();
If you aren't tripped by it, somebody else will be instead.

4. Indentation

	Do not use tabs in the actual data part.  You may use tabs
to space out to the following comments.  Trailing tabs before the
closing */ just make it hard to add further words.  Yes, making the
closing */'s on lines match up is pretty, but we have art and
museums for that.

int foob;		/* Will count instances of foob */
static char bar;	/*  ...the char matching foob */

5. Patching somebody's code

	Do not go fiddle somebody's organization just because
you think you can make it prettier.  It is especially bad form
to fiddle the indentation and layout, PLUS add some new stuff,
then hand them back the entire result.  Now they have to dig
through a bunch of indentation changes while trying to find
functional changes.

extern int x, y, z;

	VVV

extern int x;
extern int y;
extern int w;
extern int z;

	Such a change adds little, but fills our screens with
diffs.  If you take over the file AND you add comments to each
line, it might be worth it.  It sure would be easy to miss
that "w" in there at the same time, wouldn't it?

6. ANSI prototypes

	Use ANSI prototypes where possible.  The one major
pain is anonymous struct pointers.  Imagine a header
which uses an anonymous pointer (i.e., they know the name
of the struct they're pointing to, but they don't know
the definitions of the struct.)  gcc will complain about
such a prototype:

extern void my_func(struct foob *);

unless he has already seen "struct foob" at level 0 (global).

The workaround of choice is to use STRUCT_REF in <sys/types.h>.

7. ANSI void *

	Use ANSI void pointers when you're dealing with
a generic pointer value.  Do NOT do math with such a pointer.
Yes, GCC will happen to treat it as a char *.  If you're counting
on this, cast it to (char *) and then do the math.

8. C types

	Use the basic C types for most work.  If you have a
struct pointer, just name it as such.  I want:

struct foo {
	int field1;
	...
};
....
{
	struct foo *f;

	f = ...;
	f->field1 = bar;
}

And not:

typedef struct {
	int field1;
	...
} foo_t;
....

C has good basic ways for naming types, and typedef's should
not be used to hide them.  The exceptions are industry-recognized
types like "ushort" (unsigned short) and so forth.

9. #define's

	A short #define can help encapsulate a simple operation
or value into a useful name.  If you find that the number of
"#define"'s is becoming a large fraction of your header file
(or even your code!) then back off.  Make it a function.  Maybe
it'll go slower... maybe GCC will in-line it anyway.

10. Variable names

	Use short variable names.  A phone number is 7 digits
because that's the size of "name" the human mind can carry around
easily.  Keep your variables in the same class of length.  Long,
descriptive variables make code-reading cumbersome, as the mind
continually must re-parse the components of the variable name.
Globals used across source files will tend to be a little bit
longer.

- Raw text -