# 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](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack) and [clang-format](https://marketplace.visualstudio.com/items?itemName=xaver.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)](https://en.wikipedia.org/wiki/Indentation_style#BSD_KNF) for function bodies
and [Kernighan & Ritchie (K&R)](https://en.wikipedia.org/wiki/Indentation_style#K&R) style (with a few modifications stated in **General Guidelines**) everywhere else.

## Existing Literature

I recommend skimming over these for inspiration.

- [Names](https://research.swtch.com/names) - Russ Cox
- [Notes on Programming in C](http://doc.cat-v.org/bell_labs/pikestyle) - 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](https://en.wikipedia.org/wiki/Indentation_style#K&R) 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
- `fstream`s for input/output/log files are fine
- Use C's `struct`s 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++
/* 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;
}
```