Coding Guide

From TinyMUSH
Jump to: navigation, search

If you'd like to contribute code to the TinyMUSH 3 project, here are some guidelines. The less work it is for the core group of maintainers to integrate your patch, the more likely it is that your patch will be accepted in a timely manner. Consequently, for both your sake and ours, we encourage you to follow the guidelines below.

  1. The project has a patch tracking system on its SourceForge home page. Please submit patches to that system, as well as posting notification on the mailing list.
  2. Any code that you contribute to the project that is intended to be part of the main server (as opposed to a standalone module) must be licensable under the Artistic License that we use. Contributions for incorporation into the core should not require a separate license; we'll consider anything that absolutely must have its own license (which must still be compatible with the Artistic License) on a case-by-case basis.
  3. Please include appropriate help text with your code. This will both help everyone understand what you are trying to achieve, and spare someone else from needing to write the documentation.
  4. If you ou are implementing a new feature, please check to see if it exists in PennMUSH or TinyMUX 2. If it does, don't break compatibity unless you have an extremely good reason to do so; include an explanation of why you decided to do that.
  5. Make sure to patch against the latest sources in GIT. It will strongly decrease the likelihood that your patch will conflict with a recent or planned change.
  6. Read as much of the relevant existing source as you can. Try to use the existing stylistic conventions, infrastructure functions, etc. where possible. If you've come up with a much better implementation, rather than just using it in your own code, change the relevant infrastructure function, so everything else gets the benefit of your improvement.
  7. If you are implementing something similar to a feature that already exists, do not duplicate big chunks of the existing code. Refactor, so you can reuse code without having to duplicate it.
  8. Comment your code!
  9. Please try to conform to the existing style of the code. We use an indentation style that is similar to K&R, with either an eight-space (tab) or four-space indent. See this example on Wikipedia.
  10. Use ANSI C style declarations.
  11. Name things in a useful and non-profane manner. Variables and function names are all in lowercase, with an underscore used to separate words. Constants are in all uppercase. Macros typically begin with a capital letter, with the rest of the macro name lowercased, with words separated by underscores. Macros are occasionally declared all in lowercase or all in uppercase (generally when representing functions, as opposed to logic expansions and the like).
  12. Use the functions in alloc.c for allocating and freeing memory. Make use of XCALLOC to allocate arrays of structures (it avoids alignment issues). Use the buffer pool management (lbufs and the like) for strings, rather than declaring character arrays or directly malloc'ing space for strings. When you test your code, make sure you do a @list buf, and ensure you're not leaking any buffers.
  13. Do not declare a variable static unless you have ensured that there aren't any cases where it can be accidentally overwritten (through nested calls, for instance).
  14. When you are writing something into a buffer, make use of the safe_str() family of macros, if you possibly can. Don't use sprintf() unless you know that it can't possibly overflow the space allocated for the string.