* 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 example: Good: (defun erc-foo-p (...) ...) (defmacro with-erc-foo (...) ...) (defmacro define-erc-foo (...) ...) (defvar erc-frob-foo ...) Bad: (defun foo-p (...) ...) (defmacro with-foo (...) ...) (defmacro define-foo (...) ...) (defvar frob-foo ...) * ChangeLog Entries ERC's ChangeLog entries are *no longer* generated automatically from the CVS logs. As such, please try to update the `ChangeLog' file every time you commit a change. The GNU Coding Standards have some good tips for writing ChangeLog entries: http://www.gnu.org/prep/standards_40.html#SEC40 Emacs has modes to alleviate the writing of entries, see the info nodes: (info "(emacs)Change Log") and (info "(emacs)Change Logs and VC") * NEWS entries We maintain a list of user-visible changes between versions in the file NEWS. This should be of the same form as the Emacs NEWS file (viewable, as an example, via C-h n (view-emacs-news)). This file should not document internal changes, only ones which show their faces to the outside world. * 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.