forked from scott/threaded_network_chat
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# 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.
|
|
- 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;
|
|
}
|
|
```
|
|
|