Syntax Guidelines

Filed under: Exclaim Kernel

If you would like to write code for Exclaim, please make sure that your code adheres to these guidelines:

Never, I repeat, NEVER use spaces for indenting. Use 1 tab per indent, like the following:

void say_hello() {
	if(bar == foo) {
		printf("Hello!\n");
	}
}

The rule is to keep braces on the same line, like this:

void say_hello() {
	if(bar == foo) {
		something();
		do_real_hello();
	}
}

rather than:

void say_hello()
{
	if(bar == foo)
	{
		something();
		do_real_hello();
	}
}

You should always use braces rather than doing things like:

	if(bar == foo)
		something();

Keep the case on the same indentation level as the switch, and the contents of each switch block indented 1 tab from the case and switch, like so:

	switch(foo) {
	case 0:
		do_something();
		do_even_more();
		break;
	case 1:
		break_cpu();
		only_joking();
		break;
	}

Do not put spaces between a function name and the (), same goes for if, while, switch and for, like so:

if(cat == dog) {
	while(1) {
		printf("Eek!n");
	}
}

rather than:

if (cat == dog) {
	while (1) {
		printf("Eek!n");
	}
}

The Exclaim kernel and applications are licensed under the GNU General Public License version 2, therefore ALL files should bear the GPLv2 header:

/* Exclaim /description of file/
 * Copyright (C) /year/ /your name/
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2 of the GNU General Public License
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

• If you are editing a file that was already put in place: Put a new copyright line with your name under the existing ones.
• If you are making a new file: Put your name as the copyright line

Regardless of what you do above, change /description of file/ to whatever the code does. Attach this to the very start of the file. If you are in doubt on what to change parts of the header to look like, refer to an already existing file.

The Exclaim libraries, however, are licensed under the GNU Lesser General Public License version 2, therefore ALL library source files and headers should bear the LGPLv2 header:

/* Exclaim /library, i.e. C/ library - /description/
 * Copyright (C) /year/ /your name/
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of version 2 of the GNU Lesser General Public License
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

Same rules as for kernel and applications apply.

Do not use C++-style comments, like this:

// This is a comment
// This is also a comment

Use this instead:

/* This is a comment.
 * This is also a comment. */

It is preferred that comments are punctuated properly (i.e. finish with a period). Also, comments should be kept under 80 characters in length per line.

The Exclaim source code is documented with Doxygen comments. Each source file should contain the following under the license header (with a space between):

/**
 * @file
 * @brief		/Description of file/.
 */

Each global variable should be documented with a one-line comment like the following (note that the comment is started with a slash and 2 stars - this indicates that the comment is a Doxygen comment):

/** Currently executing thread. */
cpulocal thread_t *curr_thread;

Structure definitions should be documented as follows (note the use of a < in a comment on the same line as the member it is for. This is required to tell Doxygen that the comment is for the member prior to it):

/** /Description of structure/. */
typedef struct mystruct {
	list_t header;			/**< Link to mystruct list. */

	char *name;			/**< Name of the mystruct. */
	int id;				/**< ID of the structure. */

	/** Array of stuff. */
	char *array_of_stuff[CONFIG_MYSTRUCT_ARRAY];
} mystruct_t;

When using same-line comments, try to ensure that the line width does not exceed 80 characters. It is not required, but it makes reading easier for people using 80-column terminals. Note that if you have a long member definition the comment is placed on a seperate line before the member, as it cannot fit in line with the rest of the same-line comments.

Finally, ALL functions must be documented as follows:

/** /Short description of function/.
 *
 * /Longer description of function and what it does here/.
 *
 * @todo		TODO number 1.
 * @todo		TODO number 2.
 *
 * @param foo		The foo to operate on.
 * @param bar		The number of things to do.
 *
 * @return		Number of successful operations on success, negative
 *			error code on failure.
 */
int foo_operate(foo_t *foo, int bar) {

TODOs, parameters and return lines should be in the same order as shown above. TODOs, obviously, are optional if there are no TODOs for the function.

Same rules in comments section above apply for documentation comments.

Functions, generally, should be prefixed with a group saying what they're for followed by an underscore. Usually this group will be the file that they're in, for example functions in sched.c are prefixed with sched_, and functions in hash.c are hash_. There are a few exceptions that can be made to this rule to fit in with the API, for example execve in exec.c, but generally it's best to stick to this rule. If in doubt, ask in IRC.