bonsix/STYLE

The following guidelines are conducive to clear and readable code that is
consistent with the style of the rest of the Bonsai Computer System.

0. Braces are mandatory for all control flow.

1. Nested indentation should be kept to a minimum.

2. Empty lines should be placed between different kinds of statements:

	int t;

	assert(io->bufuse > 0);
	assert(io->bufuse <= io->bs);

	if ((t = write(io->fd, io->buf, io->bufuse)) < 0) {
		io->error = errno;
		t = 0;
	} else if (t > 0) {
		memmove(io->buf, &(io->buf)[t], (io->bufuse -= t));
	}

	io->bytes += t;
	io->prec  += (t > 0 && io->bufuse > 0);
	io->rec   += (t > 0 && io->bufuse == 0);

	return io;

3. Each block of code should be indented once more than the keyword which
initiated the block:

	switch (c) {
		case 'e': mode |= EQUAL;   break;
		case 'g': mode |= GREATER; break;
		case 'l': mode |= LESS;    break;
		default:  return usage(s);
	}

4. In C, spaces should be placed in control flow statements after the keyword
and before the opening brace:

	for (i = 2; i < argc; ++i) {

5. If a function, a C control flow statement, or a Rust macro has arguments that
cause the statement to be broken into multiple lines, this should be done by
placing the arguments on a new line inside the parentheses: 

	let usage = format!(
		"Usage: {} [-d delimiter] index command [args...]",
		argv[0],
	);

6. If Rust function arguments or fields are on their own lines, they should
always have a trailing comma:

	return Err(EvaluationError {
		message: format!("{}: Invalid token", i),
		code: EX_DATAERR,
	})

7. If text is on the same line as a brace, spaces should be placed after an
opening curly brace and before a closing one:

	use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };

8. If a control flow statement is short enough to be easily understood in a
glance, it may be placed on a single line:

	if !(argc < 0) { usage(program_name); }

9. In C, note everything you use from a library in a comment subsequent to its
#include statement:

	#include <unistd.h> /* close(2), getopt(3), lseek(2), read(2), write(2),
                         * optarg, optind, STDIN_FILENO, STDOUT_FILENO */

10. In Rust, place extern statements after use statements that include standard
library crates. Group alike statements:

	use std::fs::Path;

	extern crate strerror;
	extern crate sysexits;

	use strerror::StrError;
	use sysexits::{ EX_OSERR, EX_USAGE };

11. Do not use do while loops in C.

12. Adhere to the following rules from the paper The Power of 10: Rules for
Developing Safety-Critical Code [0]:
	1. Avoid complex flow constructs, such as goto and recursion.
	2. All loops must have fixed bounds. This prevents runaway code.
	3. Avoid heap memory allocation.
	4. Restrict functions to the length of a single printed page.

	6. Restrict the scope of data to the smallest possible.
	7. Check the return value of all non-void functions, or cast to void to
	indicate the return value is useless (such as in the case of using
	fprintf(3p)	to print to the standard error).
	8. Use the preprocessor sparingly.
	9. Limit pointer use to a single dereference, and do not use function
	pointers.
	10. Compile with all possible warnings active; all warnings should then be
	addressed before release of the software (for C compilers, compile with
	-Wpedantic).

13. Remember this quote from The Elements of Programming Style by Brian
Kernighan:
	Everyone knows that debugging is twice as hard as writing a program in the
	first place. So if you're as clever as you can be when you write it, how
	will you ever debug it?


References
==========

[0] <https://web.eecs.umich.edu/~imarkov/10rules.pdf>

--
Copyright © 2024 Emma Tebibyte <emma@tebibyte.media>
Copyright © Wikipedia contributors

This work is licensed under CC BY-SA 4.0. To view a copy of this license, visit
<http://creativecommons.org/licenses/by-sa/4.0/>.