.DT
style
$MUDNAME$ Creator Help
style
.SH Description
.SP 5 5
All code that creators write for $MUDNAME$ should follow certain
conventions so that future generations who may have to work with your
code are able to do so easily. One of the most important conventions
is that of double spacing: every piece of text to which players have
access should be written with two spaces between each sentence. This
simply makes the text easier to read, especially on room descriptions as
players move about. It goes without saying that all sentences should be
correctly capitalised and punctuated.
.EP
.SH Layout
.SI 5
header
includes
defines
inherits
variables
setup (if appropriate)
other functions
.EI
.SP 5 5
The above is the recommended layout for a file. The header of the file
should include the author of the file as a bare minimum, general comments
are also welcome. Includes (that is, lines beginning with #include) are
the first things evaluated, followed by defines (lines beginning with
#define). Then the parent objects are inherited, and the code's own
variables declared. If the code has a setup function, usually if it's
going to be an object with descriptions, then this should come first so
that it becomes quickly apparent what this thing is that you have coded
(besides which, if a player leaves a bug report for it, most of the time
the bugs will concern something in setup); other functions follow (if the
object uses autoloading, has commands in it or has the stat function,
these are generally put at the end).
.EP
.SH Header and comments
.SP 5 5
Each file, no matter how trivial, should generally have a header that
says who to give credit for writing the code. Additionally a brief
description of what the file does, or in case of rooms, the name/location
or similar of the room. Other things to have in the header are a list of
changes to the file (in case of more important bits of code for
backtracking purposes). Here are a few examples:
.EP
.SI 5
/**
* This is the northern end of Brush Street.
* @author Sandoz, July 2003.
*/
/**
* This handles all the methods for determining values of coins and
* the current valid set of coins. It also handles change calculation.
* This was written originaly by Pinkfish, reworked significantly by
* Deutha to add in the multiple currency areas.
* @see /std/living/money.c
* @author Pinkfish
* @changed Fixed up the code that deals with different currency areas.
* Also added money_array_from_string() and made value_from_string()
* work properly with different types of currencies - Sandoz, April 2003.
*/
.EI
.SP 5 5
For information on how to comment functions in a way compatible with the
autodoc handler (a handler that extracts comments from code and creates
help files from them), please read help autodoc.
.EP
.SH Names
.SP 5 5
For clarity, quantities from a #define should use all capital letters
while names of variables should use lower case letters. Similarly,
files included from the local directory (the same directory as contains
the file itself) should be written in quotes, e.g. #include "defs.h" ,
while those to be included from /include/ should be written in angle
brackets, e.g. #include <money.h> . Function names and variable names
are generally unrestricted, although it is recommended that you use
names that reflect what the function does or the variable stores. At
the end of each function, you should put the name of the function in
comments, e.g. } /* reset() */ , as this makes it easier to tell which
function it is that has just ended.
.EP
.SH Indentation
.SP 5 5
Possibly the most important aspect of putting code into a file is the
indentation of the lines. Indentation is important not just for making
the code legible but it can also help with debugging, tracking down
missing (or extra) brackets for example. The recommended number of
spaces to indent by is four. There is little to be gained by indenting
by more spaces since, especially on an 80 column display, it is easy to
run out of room, less than 4 spaces on the other hand will be slightly
less legible. When you have to break a line, usually in something like
a write or set_long, you should indent it again by twice the amount;
for example:
.EP
.SI 5
void setup() {
...
set_long("You are on the Street of Small Gods just northeast "
"of the Temple of Gufnork and southwest of the Temple of "
"Sandelfon. The street continues southwest and east, "
"where there is a junction with a side road.\n");
...
} /* setup() */
.EI
.SH Spacing
.SP 5 5
Just as putting spaces between words makes this piece of text easier to
read, putting spaces into your code helps anyone reading it. Generally
arguments to functions and arrays should be separated from brackets with
spaces, and commas should have spaces after them. Logical comparators
and binary operands should have spaces either side of them, although
contracting " + to "+ (or around the other way) is common. Opening
curly brackets should immmediately follow functions or if, while, etc.
statements rather than being on the following line. For example, the
following piece of code uses these conventions:
.EP
.SI 5
int list_elections() {
string ret, name, *deities;
if( !sizeof( elections ) ) {
write("There are no elections in progress.\n");
return 1;
}
deities = keys( elections );
if( sizeof( deities ) > 1 )
write("There are elections in progress for high priests of:\n");
else
write("There is an election in progress for the high "
"priest of:\n");
ret = "";
foreach( name in deities )
ret += " * "+name+": candidates are "+
query_multiple_short( elections[ name ][ 0 ] )+"; voting "
"closes at "+ctime( elections[ name ][ 1 ] ) +".\n";
printf("%-=*s", TP->query_cols(), ret );
return 1;
} /* list_elections() */
.EI
.SH See also
.SI 5
setup
.EI
