docs/CONVENTIONS

   1 This document tries to list all the conventions that the fvwm
   2 developers adhere to, either by consensus through discussion,
   3 common practice or unspoken agreement.  It is hopefully useful for
   4 the fvwm development newbie.  Do not take these 'rules' as
   5 religious duties.  All of this can be discussed if need be.  If
   6 you add items to or modify items in this list, add your name and
   7 the reasoning for the change.
   8
   9 ! = This rule *must* be followed
  10 * = Less strict rules
  11 o = Suggestions
  12
  13
  14 A. Programming Languages
  15
  16  ! The following programming languages are allowed:
  17
  18     - ANSI C
  19     - Perl
  20     - Portable /bin/sh scripts for examples.
  21
  22    All other languages - specifically C++ - are not allowed since
  23    they cause portability problems.
  24    [dv]
  25
  26 B. New Code Files
  27
  28  * There are templates for new code files in the fvwm directory.
  29    Try to always use them as they provide a clean structure of the
  30    header and code files.  Please honour the section titles.  For
  31    example, put all static functions (and only static functions)
  32    under the "local functions" section.
  33    [dv]
  34
  35  ! All .c files *must* have
  36
  37      #include "config.h"
  38
  39    as the first non-comment line.  Otherwise the settings made by
  40    the configure script may not be used.  This can cause random
  41    problems.
  42    [dv]
  43
  44  * Add a comment "/* -*-c-*- */" at the beginning to tell (x)emacs
  45    it is a C source file even if it was renamed to something like
  46    foo.c.bak.
  47    [dv]
  48
  49 C. File Names
  50
  51  * The names of the code files in the fvwm directory are in lower
  52    case.
  53    [dv]
  54
  55  * Files in the libs directory may begin with a capital 'F'.  This
  56    letter is reserved for wrapper files for third party libraries
  57    or modules.  For example, FShape is an abstraction of the
  58    XShape X server extension and FBidi is a wrapper for the
  59    fribidi library.  Do not use the 'F' for other purposes.
  60    [dv]
  61
  62 D. Copyright Notices
  63
  64  * A copy of the GPL should be at the beginning of all code files
  65    (.c) and scripts, but not at the beginning of header files
  66    (.h).
  67    [dv]
  68
  69 E. Code Formatting
  70
  71  * Follow the Linux Kernel Coding Rules.  Specifically:
  72    [dv]
  73
  74  * Indent with TABS only.  The TAB width is eight spaces.
  75
  76    Reasoning:  This limits the space available for nesting blocks
  77    in functions.  For long functions, it is easier to read.  Also,
  78    a properly formatted file can be read with any editor as long
  79    as it has at least 80 columns and a TAB width of 8 or less.
  80    [dv]
  81
  82  o Always place curly braces on a separate line.  In some cases,
  83    placing braces on the same line as other code confuses
  84    (x)emacs.
  85    [dv]
  86
  87  * Use no more than 79 columns per line.  If you have trouble to
  88    fit the code in 79 characters, think how you could move some of
  89    it to a separate function.
  90    Note:  Due to a bug in xemacs, it is sometimes not possible to
  91    start the editor window with 80 columns.  It comes up either
  92    with 79 or 81 columns.  Hence the rule to no use 80 columns per
  93    line.
  94    [dv]
  95
  96  * Try to keep functions short.  A function should not consist of
  97    more than one or two screen pages.
  98
  99    Reasoning:  Improves readability.
 100    [dv]
 101
 102  * Always keep code maintenance in mind.  Break down complex
 103    expressions into a series of smaller expressions and leave the
 104    optimizing work to the compiler.  It is of utmost importance
 105    that your code is easy to understand.
 106    [dv]
 107
 108 F. Coding
 109
 110  ! Global variables are forbidden.  Full stop.
 111    [dv]
 112
 113  * Chose meaningful function and variable names.  But keep in mind
 114    that C guarantees only 32 character to be used.
 115    [dv]
 116
 117  * Flag variables should always begin with auxiliary verbs.  For
 118    example:  is_new, do_restart, has_this, use_that, etc.
 119
 120    Reasoning:  when you look at the flag variable out of context,
 121    you immediately recognise it as a flag.  If you name a flag for
 122    example restart or new, this may not be clear without looking
 123    up the definition.
 124    [dv]
 125
 126  o The names of local helper functions with limited functionality
 127    may begin with two underscores.  For example
 128    "__local_function".  These functions *must* be declared static
 129    and *must not* be ever exported.
 130
 131    Reasoning:  this is a visual aid for code maintenance.  When
 132    you encounter a function with such a name you know that it
 133    contains limited local functionality.
 134    [dv]
 135
 136  * Comment your code liberately, but do not explain the obvious.
 137    It is often better to chose meaningful function and variable
 138    names.
 139
 140 G. Formatting text files
 141
 142  * Indent text files with spaces and do not use more than 79
 143    colums.  Do not use TABs in text files.
 144    [dv]
 145
 146  * Some of the supplementary text files in the distribution are
 147    regulary posted to mailing lists.  According to the most strict
 148    version of the Nettiquette I found, no more than 67 columns
 149    must be used in these files.  These files are
 150
 151     - NEWS
 152     - FAQ
 153     - ANNOUNCE
 154
 155    Note:  (x)emacs auto-fill-mode is very useful to do this.
 156    [dv]
 157
 158  o You may add the literal string "-*-text-*-" in the first line
 159    of the file to tell (x)emacs that it is a text file.
 160    [dv]
 161
 162  ! If you are unsure about your knowledge of the English language,
 163    ask for help on the mailing list when you write documentation.
 164    [dv]
 165
 166  o In English, the full stop ('.') or colon (':') is usually
 167    followed by two spaces instead of one.
 168
 169    Reasoning:  Improves readability.
 170    [dv]
 171
 172 H. Release Management
 173
 174  * New patches may be tried out in the development versions (with
 175    an odd second digit in the version number).  Features may be
 176    changed, renamed or removed at any time.
 177    [dv]
 178
 179  ! In the stable versions, features can not easily be changed or
 180    removed.  For backwards compatibility think of the least
 181    disrupting way of doing changes.
 182    [dv]
 183
 184  * As you may conclude from above two items, try to never add
 185    experimental features close to the next stable release.  Once
 186    the feature is made available in a stable version, it becomes
 187    virtually impossible to back it out or change its syntax.
 188    [dv]
 189
 190 I. Maintaining the NEWS
 191
 192  * In the development versions, only new, removed and changed
 193    features must be mentioned in the NEWS.
 194    [dv]
 195
 196  * There is currently some discussion whether features that were
 197    added in a prior development release and are renamed or removed
 198    later, before the next stable release, should be deleted from
 199    the NEWS or not.
 200    [dv]
 201
 202  ! In the stable versions, all changes to any file *must* be
 203    mentioned in the NEWS.  This is important since the NEWS file
 204    is sent as part of the release announcement.  Users must be
 205    able to judge whether they want the new release or not.
 206    [dv]
 207
 208 J. Maintaining the ChangeLog
 209
 210  ! The ChangeLog is meant to ease code maintenance.  With proper
 211    and detailed entries, the ChangeLog can dramatically reduce the
 212    time needed to find problems and fix bugs.
 213    [dv]
 214
 215  ! Every change *must* be ChangeLog'ed as detailed as possible.
 216    To generate a ChangeLog entry while you are coding, press "C-x
 217    4 a" in (x)emacs.
 218    [dv]
 219
 220  ! If at all possible, put *all* names of modified files and
 221    functions in the ChangeLog.
 222    [dv]
 223
 224  * Please do not use wildcards in the ChangeLog entries.  If you
 225    modified fvwm.c and fvwm.h, do not write "fvwm.[ch]" or
 226    "fvwm.{c,h}" or "fvwm.*".
 227
 228    Reasoning:  wildcards make it virtually impossible to grep
 229    through the ChangeLog.
 230    [dv]
 231
 232 K. Maintaining Man Pages
 233
 234  ! Every feature must be described with all options in the man
 235    page.
 236    [dv]
 237
 238  * The man page has its own formatting rules.  See fvwm/fvwm.1.in
 239    for details.
 240    [dv]