threaded_network_chat/STYLE.md

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 and 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) 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.
    • 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,
• 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;
}