docs/coding-style.txt

   1 This file contains various development notes useful when coding srvx.
   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
  12 shipped with srvx.  ALL other headers must be conditional.
  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).
  19 Code in srvx should follow this convention.
  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.