.DT
style
Divided Sky creator help
style
.SH Description
.SP 5 5
All code that creators write for Divided Sky should follow certain
conventions so that future generations who may have to work with your
code are able to do so easily. The most important convention 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
includes
defines
inherits
variables
setup (if appropriate)
other functions
.EI
.SP 5 5
The above is the recommended layout for a file. Includes (that is,
lines beginning with #include) are the first things evaluated, followed
by defines (lines beginning with #define). Then the parents 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 or has
the stat function, these are generally put at the end).
.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 minimum number of spaces
to indent is two, but three or four spaces are recommended. 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. 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() {
int i;
string text, *deities;
if ( !m_sizeof( elections ) ) {
write( "There are no elections in progress.\n" );
return 1;
}
deities = m_indices( 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" );
text = "";
for ( i = 0; i < sizeof( deities ); i++ )
text += " * "+ deities[ i ] +": candidates are "+
query_multiple_short( elections[ deities[ i ] ][ 0 ] ) +
"; voting closes at "+
ctime( elections[ deities[ i ] ][ 1 ] ) +".\n";
printf( "%-=*s", (int)this_player()->query_cols(), text );
return 1;
} /* list_elections() */
.EI
.SH See also
.SI 5
setup
.EI
