[people/ms/network.git] / docs / CODING_STYLE

This document attempts to explain basic styles and guidelines for the IPFire
network codebase. New code should conform to these standards. Of course every
rules has an exception, but still this should be followed as closely as
possible.

# Naming & Formatting Code

## Whitespace

Tabs. No spaces at an end of a line.

## Line Length

Lines should not be longer than 80 characters. 120 is definitely the hard limit.

## Indentation

One tab.

## Control Structures

	if cmd ...; then
		cmd ...
	fi

	while cmd ...; do
		cmd ...
	done

	local i
	for i in 1 2 3; do
		cmd ...
	done

	case "${var}" in
		1)
			cmd ...
			;;
		2)
			cmd ...
			;;
	esac

## Variables

Variables must be used with curly brackets: ${var}, NOT $var

Global variables should be ${UPPERCASE}. Local variables should be ${lowercase}.

## Function Declarations

	# This explains what the function is doing and
	# how it is supposed to be used...
	foo() {
		local arg1=${1}
		local arg2=${2}

		cmd ...
		cmd ...
	}

Arguments must be parsed as early as possible to give them meaningful names
instead of using ${1}, ${2}, ...

## Functions Exit Codes

Functions must always return a clean error code out of EXIT_OK, EXIT_ERROR,
EXIT_TRUE, EXIT_FALSE or others so that things are easily readable.

## Assertions

assert() should be used to catch any errors at runtime as early as possible.

They should not used to catch any issues that the user needs to be informed of.

The developer cannot rely on the statement being executed since we might skip the
executing of assertions when ever we need to.

## Lists

Lists of anything should be alphabetically ordered as long as there is no other
(i.e. better) reason to sort them otherwise. IPv6 is always first.

## Logging & Error Messages

Error messages must be short and clear. No trailing full stops.

They should always be passive sentences and present tense.
Commit	Line	Data
dd46582c MT	1	This document attempts to explain basic styles and guidelines for the IPFire
	2	network codebase. New code should conform to these standards. Of course every
	3	rules has an exception, but still this should be followed as closely as
	4	possible.
	5
	6	# Naming & Formatting Code
	7
	8	## Whitespace
	9
	10	Tabs. No spaces at an end of a line.
	11
	12	## Line Length
	13
	14	Lines should not be longer than 80 characters. 120 is definitely the hard limit.
	15
	16	## Indentation
	17
	18	One tab.
	19
	20	## Control Structures
	21
	22	if cmd ...; then
	23	cmd ...
	24	fi
	25
	26	while cmd ...; do
	27	cmd ...
	28	done
	29
	30	local i
	31	for i in 1 2 3; do
	32	cmd ...
	33	done
	34
	35	case "${var}" in
	36	1)
	37	cmd ...
	38	;;
	39	2)
	40	cmd ...
	41	;;
	42	esac
	43
	44	## Variables
	45
	46	Variables must be used with curly brackets: ${var}, NOT $var
	47
	48	Global variables should be ${UPPERCASE}. Local variables should be ${lowercase}.
	49
	50	## Function Declarations
	51
	52	# This explains what the function is doing and
	53	# how it is supposed to be used...
	54	foo() {
	55	local arg1=${1}
	56	local arg2=${2}
	57
	58	cmd ...
	59	cmd ...
	60	}
	61
	62	Arguments must be parsed as early as possible to give them meaningful names
	63	instead of using ${1}, ${2}, ...
	64
65	## Functions Exit Codes
66
67	Functions must always return a clean error code out of EXIT_OK, EXIT_ERROR,
68	EXIT_TRUE, EXIT_FALSE or others so that things are easily readable.
69
70	## Assertions
71
72	assert() should be used to catch any errors at runtime as early as possible.
73
74	They should not used to catch any issues that the user needs to be informed of.
75
76	The developer cannot rely on the statement being executed since we might skip the
77	executing of assertions when ever we need to.
78
79	## Lists
80
81	Lists of anything should be alphabetically ordered as long as there is no other
82	(i.e. better) reason to sort them otherwise. IPv6 is always first.
83
84	## Logging & Error Messages
85
86	Error messages must be short and clear. No trailing full stops.
87
88	They should always be passive sentences and present tense.