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 `_long_options') -- 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 user 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 `[[ nmm -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
    and `name' describes what can be configured.
    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).