125 lines
3.8 KiB
Plaintext
125 lines
3.8 KiB
Plaintext
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/>.
|