For now this is just a list of things one should or shouldn't do.

1)  Use the functions `_files' and `_path_files' instead of `compgen'
    with the `-f', `-/', or `-g' options.
2)  *Never* use `compgen' with the `-s' option. This can always be done 
    by a call to `compadd' which is faster.
3)  Using `compgen' with the `-k' option should only be done if a) the
    array is already existent or b) it is very large (several hundred
    or thousend elements). In other cases using `compadd' is faster.
4)  Supply match specifications to `compadd' and `compgen' if there are 
    sensible ones.
5)  Use `_description' when adding matches with `compadd' or
    `compgen'. Use `_message' in places where no matches can be
    generated. If you want to add different types of matches, add them
    with multiple calls to `compadd' or `compgen', supplying different
    descriptions.
6)  Use helper functions that do option completion for you (like
    `_arguments' and `_values') -- it will make your life much
    easier.
7)  Use helper functions like `_users' and `_groups' instead of direct
    calls to `compgen -u' or some ad hoc mechanisms to generate such
    information. This ensures that users can change the way these things 
    will be completed everywhere by just using their own implementations 
    for these functions.
8)  Make sure that the return value of your functions is correct: zero
    if matches where added and non-zero if no matches were found.
    In some cases you'll need to test the value of `$compstate[nmatches]'
    for this. This should always be done by first saving the old value
    (`local nm="$compstate[nmatches]"') and later comparing this with
    the current value after all matches have been added (e.g. by
    writing `[[ nm -ne compstate[nmatches] ]]' at the end of your
    function). This guarantees that your functions will be re-usable
    because calling functions may rely on the correct return value.
9)  In places where different behaviors may be useful, add a
    configuration key to allow users to select the behavior they
    prefer. Names for configuration keys should look like `prefix_name',
    where `prefix' is the (probably abbreviated) name of your function
    (without any leading underscore) and `name' describes what can be
    configured.
    If you want to have this completion function to be included in the
    distribution, it would help if you describe the configuration key
    at the end of the `compsys.yo' manual.
    When testing the values of configuration keys, the empty string
    should result in the same behavior as if the key were unset. This
    can be achieved by the test `[[ -n "$compconfig[prefix_name]" ]]'.
10) When writing helper functions that generate matches, the arguments
    of these should be given unchanged to `compadd' or `compgen' (if
    they are not used by the helper function itself).
11) When option names are generated as possible matches, add them *with*
    the `-', `+', or `--' at the beginning. This is the style used 
    throughout the completion system from the distribution and makes it
    easier to distinguish options from other matches in completion lists.
    Also, when adding options as matches, put them in a sorted group
    named `option'. The best way to do this is by using the `_description'
    helper function as in:

      local expl
      _description expl option
      compadd "$expl[@]" - <option-names ...>

    Also, before adding options as possible matches, test the
    `option_prefix' configuration key. If it set and it doesn't contain
    the sub-string `!cmd' (where `cmd' is the name of the command that
    is completed for) options should only be added if the prefix character
    (`-' or `+') is on the line or if no other useful matches could be 
    generated. This can be achieved by first generating these other matches
    (if any) and then using a test like:

      if [[ nm -eq "$compstate[nmatches]" ||
            -z "$compconfig[option_prefix]" ||
            "$compconfig[option_prefix]" = *\!${words[1]}* ||
            "$PREFIX" = [-+]* ]]; then
        # Add options...
      fi

    Finally, it is good style to display descriptions for options that
    aren't self-explanatory. See the `_display' and `_describe' functions
    and their uses in `_arguments'.

    All this should make it look like a really good idea to just use the
    supplied `_arguments' function to complete options.
12) If at all possible, completion code for a command or a suite of
    commands should go into only one file. If a command has sub-commands,
    implementing aa state-machine might be a good idea. See the `_rpm' 
    and `_pbm' files for examples of different styles. Also see the
    documentation for `_arguments' and `_values' for two functions
    that may help you with this.
13) If a completion function generates completely different types of
    completions (for example, because the comamnd has several
    completely different modes), it should allow users to define
    functions that separately override the behavior for these
    different types. This can easily be achieved by using the
    `funcall' utility function, as in:

      funcall ret _command_$subcommand && return ret

    This will try to call the function `_command_$subcommand' and if
    it exists, it will be called and the completion function exits
    with its exit status. After this call to `funcall' the completion
    function would contain the code for the default way to generate
    the matches.
    See the `_rpm' and `_nslookup' files for examples.