erc / HACKING.upstream

Full commit
* Hacking on ERC 101                                            -*- outline -*-

* Function/variable naming conventions

The Emacs Lisp manual has some good advice on coding conventions
(info "(elisp)Tips").  Remember, above all, that Emacs does not have a
package system, so prefix all global variables/functions with `erc-'.
If you have a macro that follows the standard `with-foo' pattern, or
`define-foo' pattern, you can probably get away with naming it without
a prefix, should it not conflict with an existing symbol, it's
probably a good idea to have `erc' somewhere in the name.  For

    (defun erc-foo-p (...) ...)

    (defmacro with-erc-foo (...) ...)

    (defmacro define-erc-foo (...) ...)

    (defvar erc-frob-foo ...)


    (defun foo-p (...) ...)

    (defmacro with-foo (...) ...)

    (defmacro define-foo (...) ...)

    (defvar frob-foo ...)

* ChangeLog Entries

ERC's ChangeLog entries are generated automatically from the CVS
logs.  As such, please try to write log entries in ChangeLog form.
The GNU Coding Standards have some good tips for writing ChangeLog

Emacs has modes to alleviate the writing of entries, see the info
  (info "(emacs)Change Log")
  (info "(emacs)Change Logs and VC")
The latter is probably slightly less relevant to us, since we don't
have a separate manually maintained ChangeLog.

If you do use these helpers and then cut and paste into
the *cvs-commit* buffer, please remove the leading header line and
the leading spaces and module names, since they get reconstructed

M-x add-change-log-entry RET might give something like this:

| 2004-03-04  Lawrence Mitchell  <>
|	* erc.el (erc-foo-p): New function.

We only want the following in the cvs log:

| (erc-foo-p): New function.

If you write ChangeLog entries using C-x 4 a (for example), and save
the file, when you come to commit, you can type C-c C-a to
automatically insert the correct entry.  This saves doing things by
hand as described above.

* Documentation

If you add a new function or variable, or change an existing one,
please add a docstring describing what it does.  Again, there are
certain conventions to follow which are detailed at length in:

  (info "(elisp)Tips")

The most important:

** Docstrings

Each function should have a docstring summarising what the function
does.  The first line should be able to stand on its own (for
apropos).  You should generally try and use the imperative form in
docstrings.  e.g. "Return non-nil if...", rather than "Returns
non-nil if..."
Similarly, variables should have a docstring describing what the
variable controls, and what different values mean.  User-visible
variables should start the docstring with a "*".  Again, the first
sentence should stand on its own as a description of the variable
(for apropos and eldoc-mode).

** Function arguments

Arguments should, where possible, have descriptive names.  This is
especially useful for those of us who use eldoc-mode.  Note also,
that, since elisp is a lisp-2, we can call an argument which is a
list "list", rather than "lst", or some other lisp-1ism.

You can catch a lot of these problems if you use checkdoc.  M-x
checkdoc-defun RET on a function will pick up on most errors.

* Other conventions

Compatibility functions for Emacs/XEmacsisms should go in erc-compat,
and be prefixed with `erc-'.

ERC modules should be defined with `define-erc-module'.

Some of the code in ERC is rather crufty, and could do with cleaning
up, don't necessarily take all of it as being a wonderful example of
coding standards.