add style guidelines STYLE.md

STYLE.md

@@ -0,0 +1,123 @@
+# Project Coding Style
+
+**Subject to change, let's please discuss this.**
+
+This is a less extreme version of the style I generally follow, and unless someone has a much better style I would
+like to use this one for code we will be collaborating on. Feel free to ignore this if you plan for your own code to
+be entirely your responsibility.
+
+Also don't swear on anything we expect to present to the professor.
+
+**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.**
+
+Follow the instructions in the previous link to set up the  correctly.
+
+## 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.
+	- `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 120 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,
+- 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;
+}
+```
+
+