ct/STYLE.md

Project Coding Style

These are guidelines for the coding style for this project. Most of it should be handled automatically by clang-format if you set it up correctly.

Break any rules that completely destroy your productivity.

Please install the C/C++ Extension Pack and clang-format for Visual Studio Code.

TL;DR

Call files .cc instead of .c or .cpp and use .h headers for everything.

If you follow the setup instructions you should be fine. Otherwise:

Use BSD Kernel Normal Form (KNF) for function bodies and Kernighan & Ritchie (K&R) style (with a few modifications stated in General Guidelines) everywhere else.

Existing Literature

I recommend skimming over these for inspiration.

• Names - Russ Cox
• Notes on Programming in C - Rob Pike

General Guidelines

• Use 8-width tabs, not spaces, for indentation.
• If you copy code from online, copy it by hand.
• Use K&R style for indentation and brace placement where possible.
  • When writing function bodies:
    • return type goes on its own line,
    • function name() is on a line below that, and
    • open bracket { after that.
  • no brackets on for, if, while, etc. statements that only contain one line
• Use /* comments */ for permanent comments, // comments for temporary ones e.g. TODO's or notices
• Try to make every line 100 characters wide or less.
• Start source files as .cc straight away, even if they're pure C.

C++-specific guidelines

• file extension: .cc, .h
• C++ strings are fine
• Vectors are fine
• Use printf and co., not std::cout, unless somehow absolutely necessary
• fstreams for input/output/log files are fine
• Use C's structs instead of objects unless you really really need an object.
• Use C-style type casting where possible

TL;DR pretend you're using C with basic modern conveniences. When in doubt, ask.

Naming and Abbreviations

The length of a function name, variable name, et cetera should be directly proportional to its importance and lifetime.

Don't

• abbreviate global variables EVER,
• mention the data type in a variable name,
• use a full word where an abbreviation will do
  • (especially not in a variable that will die 5 lines later),
• use single-letter abbreviations for anything that lasts more than 15 lines, or
• abbreviate a word when an apt abbreviation does not exist.

Do

• abbreviate extremely short-lived variables to one letter,
  • e.g. for (int index = 0; index < 10; i++) -> for (int i = 0; i < 10; i++)
• break any rule if following it ruins the readability

Source File layout

/* C++ includes */
#include <iostream>

/* C (.h) includes */
#include <stdio.h>

/* local header includes */
#include "unicorns.h"

/* "using" directives */
using namespace std;

/* global constants */
const int life = 42;

/* global variables */
int degrees = 90;

/* function prototypes */
int div_numb(int n, int d);

/* main function body */
int
main(int argc, char *argv[])
{
	int numerator = 32;
	int denominator = 16;
	int result;
	
	puts("What is 32 divided by 16?");
	
	result = div_numb(32, 16);

	return 0;
}

/* other function bodies */
int
div_numb(int n, int d)
{
	return n / d;
}