This document tries to list all the conventions that the fvwm
developers adhere to, either by consensus through discussion,
common practice or unspoken agreement.  It is hopefully useful for
the fvwm development newbie.  Do not take these 'rules' as
religious duties.  All of this can be discussed if need be.  If
you add items to or modify items in this list, add your name and
the reasoning for the change.

! = This rule *must* be followed
* = Less strict rules
o = Suggestions


A. Programming Languages

 ! The following programming languages are allowed:

    - ANSI C
    - Perl
    - Portable /bin/sh scripts for examples.

   All other languages - specifically C++ - are not allowed since
   they cause portability problems.
   [dv]

B. New Code Files

 * There are templates for new code files in the fvwm directory.
   Try to always use them as they provide a clean structure of the
   header and code files.  Please honour the section titles.  For
   example, put all static functions (and only static functions)
   under the "local functions" section.
   [dv]

 ! All .c files *must* have

     #include "config.h"

   as the first non-comment line.  Otherwise the settings made by
   the configure script may not be used.  This can cause random
   problems.
   [dv]

 * Add a comment "/* -*-c-*- */" at the beginning to tell (x)emacs
   it is a C source file even if it was renamed to something like
   foo.c.bak.
   [dv]

C. File Names

 * The names of the code files in the fvwm directory are in lower
   case.
   [dv]

 * Files in the libs directory may begin with a capital 'F'.  This
   letter is reserved for wrapper files for third party libraries
   or modules.  For example, FShape is an abstraction of the
   XShape X server extension and FBidi is a wrapper for the
   fribidi library.  Do not use the 'F' for other purposes.
   [dv]

D. Copyright Notices

 * A copy of the GPL should be at the beginning of all code files
   (.c) and scripts, but not at the beginning of header files
   (.h).
   [dv]

E. Code Formatting

 * Follow the Linux Kernel Coding Rules.  Specifically:
   [dv]

 * Indent with TABS only.  The TAB width is eight spaces.

   Reasoning:  This limits the space available for nesting blocks
   in functions.  For long functions, it is easier to read.  Also,
   a properly formatted file can be read with any editor as long
   as it has at least 80 columns and a TAB width of 8 or less.
   [dv]

 o Always place curly braces on a separate line.  In some cases,
   placing braces on the same line as other code confuses
   (x)emacs.
   [dv]

 * Use no more than 79 columns per line.  If you have trouble to
   fit the code in 79 characters, think how you could move some of
   it to a separate function.
   Note:  Due to a bug in xemacs, it is sometimes not possible to
   start the editor window with 80 columns.  It comes up either
   with 79 or 81 columns.  Hence the rule to no use 80 columns per
   line.
   [dv]

 * Try to keep functions short.  A function should not consist of
   more than one or two screen pages.

   Reasoning:  Improves readability.
   [dv]

 * Always keep code maintenance in mind.  Break down complex
   expressions into a series of smaller expressions and leave the
   optimizing work to the compiler.  It is of utmost importance
   that your code is easy to understand.
   [dv]

F. Coding

 ! Global variables are forbidden.  Full stop.
   [dv]

 * Chose meaningful function and variable names.  But keep in mind
   that C guarantees only 32 character to be used.
   [dv]

 * Flag variables should always begin with auxiliary verbs.  For
   example:  is_new, do_restart, has_this, use_that, etc.

   Reasoning:  when you look at the flag variable out of context,
   you immediately recognise it as a flag.  If you name a flag for
   example restart or new, this may not be clear without looking
   up the definition.
   [dv]

 o The names of local helper functions with limited functionality
   may begin with two underscores.  For example
   "__local_function".  These functions *must* be declared static
   and *must not* be ever exported.

   Reasoning:  this is a visual aid for code maintenance.  When
   you encounter a function with such a name you know that it
   contains limited local functionality.
   [dv]

 * Comment your code liberately, but do not explain the obvious.
   It is often better to chose meaningful function and variable
   names.

G. Formatting text files

 * Indent text files with spaces and do not use more than 79
   colums.  Do not use TABs in text files.
   [dv]

 * Some of the supplementary text files in the distribution are
   regulary posted to mailing lists.  According to the most strict
   version of the Nettiquette I found, no more than 67 columns
   must be used in these files.  These files are

    - NEWS
    - FAQ
    - ANNOUNCE

   Note:  (x)emacs auto-fill-mode is very useful to do this.
   [dv]

 o You may add the literal string "-*-text-*-" in the first line
   of the file to tell (x)emacs that it is a text file.
   [dv]

 ! If you are unsure about your knowledge of the English language,
   ask for help on the mailing list when you write documentation.
   [dv]

 o In English, the full stop ('.') or colon (':') is usually
   followed by two spaces instead of one.

   Reasoning:  Improves readability.
   [dv]

H. Release Management

 * New patches may be tried out in the development versions (with
   an odd second digit in the version number).  Features may be
   changed, renamed or removed at any time.
   [dv]

 ! In the stable versions, features can not easily be changed or
   removed.  For backwards compatibility think of the least
   disrupting way of doing changes.
   [dv]

 * As you may conclude from above two items, try to never add
   experimental features close to the next stable release.  Once
   the feature is made available in a stable version, it becomes
   virtually impossible to back it out or change its syntax.
   [dv]

I. Maintaining the NEWS

 * In the development versions, only new, removed and changed
   features must be mentioned in the NEWS.
   [dv]

 * There is currently some discussion whether features that were
   added in a prior development release and are renamed or removed
   later, before the next stable release, should be deleted from
   the NEWS or not.
   [dv]

 ! In the stable versions, all changes to any file *must* be
   mentioned in the NEWS.  This is important since the NEWS file
   is sent as part of the release announcement.  Users must be
   able to judge whether they want the new release or not.
   [dv]

J. Maintaining the ChangeLog

 ! The ChangeLog is meant to ease code maintenance.  With proper
   and detailed entries, the ChangeLog can dramatically reduce the
   time needed to find problems and fix bugs.
   [dv]

 ! Every change *must* be ChangeLog'ed as detailed as possible.
   To generate a ChangeLog entry while you are coding, press "C-x
   4 a" in (x)emacs.
   [dv]

 ! If at all possible, put *all* names of modified files and
   functions in the ChangeLog.
   [dv]

 * Please do not use wildcards in the ChangeLog entries.  If you
   modified fvwm.c and fvwm.h, do not write "fvwm.[ch]" or
   "fvwm.{c,h}" or "fvwm.*".

   Reasoning:  wildcards make it virtually impossible to grep
   through the ChangeLog.
   [dv]

K. Maintaining Man Pages

 ! Every feature must be described with all options in the man
   page.
   [dv]

 * The man page has its own formatting rules.  See fvwm/fvwm.1.in
   for details.
   [dv]
