[irc/evilnet/x3.git] / docs / coding-style.txt

This file contains various development notes useful when coding X3.

HEADER FILES
------------
If a file or feature is not defined in ANSI C89, an autoconf feature
test should be used to verify that it is supported.  ANSI C89
specifies that the following header files exist:
  <assert.h> <ctype.h> <errno.h> <float.h> <limits.h> <locale.h>
  <math.h> <setjmp.h> <signal.h> <stdarg.h> <stddef.h> <stdio.h>
  <stdlib.h> <string.h> <time.h>
You may unconditionally include the above headers, or any that are
shipped with X3.  ALL other headers must be conditional.

DEBUG MODE
----------
Many libraries are in debug mode by default, and require the C
preprocessor symbol NDEBUG to be set to disable the debug features
(this is inspired by the behavior of assert() from the C standard).
Code in X3 should follow this convention.

ASSERTIONS
----------
If you know that a certain condition is illegal, you should use the
assert() macro to verify that it is false.  Please do NOT silently
fail by returning in these conditions.

HELP FILES
----------
To maintain consistency, this is the format being used for the syntax
examples in the help files:
  - Text constants have no brackets around them
  - Required arguments use <description-of-argument>
  - Optional arguments use [description-of-argument]
        Example: /msg $S COMMAND <arg1> [arg2]
                Where COMMAND is a constant, arg1 is required, arg2 is optional
  - If arguments have different valid values, separate them with a |
        Example: /msg $S COMMAND <a|b|c> [foo|bar|baz]
  - Arguments that are optional but have an extra argument (optional or not)
    when they are used have this format: [<arg1> <arg2>] or [<arg1> [arg2]]
  - Repeating arguments have this format: <arg1> <arg2> [<arg1> <arg2>]...
    where both arg1 and arg2 are required for each repetition. If only one
    argument is used in each repetition, no <> goes around the argument name
    ([arg1]...)
  - Commands like ChanServ's SET have the format /msg $S SET [<option> [value]]
  - If there is a special case not covered above, try to find another command
    that has a similar syntax, and adapt it. If that is not possible, use
    something that makes sense.
Commit	Line	Data
ceafd592	1	This file contains various development notes useful when coding X3.
d76ed9a9	2
	3	HEADER FILES
	4	------------
	5	If a file or feature is not defined in ANSI C89, an autoconf feature
	6	test should be used to verify that it is supported. ANSI C89
	7	specifies that the following header files exist:
	8	<assert.h> <ctype.h> <errno.h> <float.h> <limits.h> <locale.h>
	9	<math.h> <setjmp.h> <signal.h> <stdarg.h> <stddef.h> <stdio.h>
	10	<stdlib.h> <string.h> <time.h>
	11	You may unconditionally include the above headers, or any that are
ceafd592	12	shipped with X3. ALL other headers must be conditional.
d76ed9a9	13
	14	DEBUG MODE
	15	----------
	16	Many libraries are in debug mode by default, and require the C
	17	preprocessor symbol NDEBUG to be set to disable the debug features
	18	(this is inspired by the behavior of assert() from the C standard).
ceafd592	19	Code in X3 should follow this convention.
d76ed9a9	20
	21	ASSERTIONS
	22	----------
	23	If you know that a certain condition is illegal, you should use the
	24	assert() macro to verify that it is false. Please do NOT silently
	25	fail by returning in these conditions.
	26
	27	HELP FILES
	28	----------
	29	To maintain consistency, this is the format being used for the syntax
	30	examples in the help files:
	31	- Text constants have no brackets around them
	32	- Required arguments use <description-of-argument>
	33	- Optional arguments use [description-of-argument]
	34	Example: /msg $S COMMAND <arg1> [arg2]
	35	Where COMMAND is a constant, arg1 is required, arg2 is optional
	36	- If arguments have different valid values, separate them with a \|
	37	Example: /msg $S COMMAND <a\|b\|c> [foo\|bar\|baz]
	38	- Arguments that are optional but have an extra argument (optional or not)
	39	when they are used have this format: [<arg1> <arg2>] or [<arg1> [arg2]]
	40	- Repeating arguments have this format: <arg1> <arg2> [<arg1> <arg2>]...
	41	where both arg1 and arg2 are required for each repetition. If only one
	42	argument is used in each repetition, no <> goes around the argument name
	43	([arg1]...)
	44	- Commands like ChanServ's SET have the format /msg $S SET [<option> [value]]
	45	- If there is a special case not covered above, try to find another command
	46	that has a similar syntax, and adapt it. If that is not possible, use
	47	something that makes sense.