The PennMUSH code style

Submitted by javelin on Wed, 2003-01-29 00:09

The PennMUSH devteam have adopted some coding conventions, which are listed below. If you use these conventions, your hacks are more likely to work on multiple systems, and will be easier for me to integrate into new patchlevels.

  • Use ANSI C style. All functions should be explicitly prototyped, and function definitions should use the ANSI C style. Although PennMUSH does contain some function definitions in the K&R style, they are being replaced by ANSI C definitions as the devteam rewrites sections of the code.
  • All source files should #include "config.h" before any other include file (except perhaps copyright.h) and should #include "confmagic.h" after all other include files. This lets the file take full advantage of the autoconfiguration script. You usually want to #include "conf.h" after "config.h" and any files, but before any other PennMUSH header file.
  • All header files should be idempotent. That's a fancy way of saying that they should be set up like this:
    #ifndef _MYFOO_H
    #define _MYFOO_H
    ...header file here...
    #endif  /* _MYFOO_H */

    This protects you if the file gets included twice by mistake.

  • If you're doing string handling, learn how to properly use the PennMUSH safe_* functions (e.g. safe_str, safe_chr, safe_integer, safe_format) to avoid buffer overflows.
  • Use ISO C 9899 functions when possible. For example, use memcpy in preference to bcopy, and strchr in preference to index
  • Signal handlers return Signal_t, defined through autoconfiguration. If SIGNALS_KEPT is defined, you don't have to reset signals in the handler.
  • malloc returns Malloc_t, and calls to free should have their parameters cast as (Malloc_t). I.e.: free((Malloc_t)buff);
  • Use mush_malloc(size to malloc,"name of mem_check") and mush_free((Malloc_t) ptr to free, "name of mem_check") when possible. These are macros which are preprocessed to plain old malloc/free when MEM_CHECK is not defined, and which call a function in memcheck.c to add/delete a mem_check before doing the malloc/free when MEM_CHECK is defined. You still need to add MEM_CHECK's manually if you get your memory by strdup or safe_uncompress or something.
  • Use the UPCASE() and DOWNCASE() macro to get the uppercase or lowercase versions of a character. The autoconfig checks whether toupper() can accept only lower-case letters, and defines UPCASE to protect toupper. If toupper() is safe, UPCASE() is defined as toupper() to be more efficient.
  • Learn about Penn's typedefs and macros, and use them when you can. This requires reading header files and examples in the source code.
  • The code follows a standard indentation scheme, which is documented in src/Makefile under the 'indent' target. It requires GNU indent 1.9 or later. You can use 'make indent' to reindent your code. Please re-indent before making context diffs for patches.
  • Document your code. As we revise the PennMUSH code, we're moving toward using doxygen ( http://www.doxygen.org ) to help us generate html documentation of the code.