initial commit

2026-03-23 17:01:32 -05:00
parent d3c52fd18a
commit 33f7d4bcc4
16 changed files with 767 additions and 9 deletions
--- a/STYLE.md
+++ b/STYLE.md
@@ -0,0 +1,117 @@
+# 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;
+}
+```
+