CODING STANDARDS
================

There are several reasons to ask everyone to use uniform code standards
in their code:

- It makes the code much more readable, not only for others, but also for
  yourself if you have to read or alter the code six months after you
  produced it. In this respect type declarations are especially useful to
  understand the code since it is easier to comprehend the functionality
  if you know the types of parameters and return values.
- Since it is easier for others to read, and therefore easier to understand
  what you have done, it will be easier for others to help you in case of
  any problems. This goes both ways naturally.
- Type declarations are especially useful to shows bugs in your code that
  would otherwise only surface in runtime errors, so it will aid you debug
  your code.
- Some of the standards mentioned are better for the memory-usage or
  may in the future indeed speed up the evaluation of the code.
- Code that is to be included in the mudlib must obey these standards since
  we consider them very useful. You are encouraged to use them for your
  domain code too, but that is not mandatory.

STANDARDS
=========

- Always use 4 spaces between indentation levels.

- Place the { and } on separate lines, on the old level of indentation.

- Use only one statement per line, even for very short statements.

- Long statements should be broken over several lines. Normally lines
  should be smaller than 80 characters. Reading lines exceeding 80
  characters can be very inhandy and printing them is even worse.

- Reserved words, like the LPC commands i.e. 'if' and 'while', should be
  followed by a space before the following breaket '('. Normal function-
  names i.e. 'create_object', should not have a space between the function
  name and the following breaket '('.

- In if-else-statements you should put the if-statement and the command
  executed if it comes true on separate lines, preferably even separated
  by lines with { and }. The same goes for for- and while-loops. It
  improves readability to use { and } even if only one statement needs to
  be executed in the 'if', 'else', 'for' or 'while'.

- Operators like '+' should be surrounded by spaces, ergo 'a + b'. The
  exception to this is '->' which is used in the form 'a->b'.

- The header of a file should always contain a comment block that includes
  the filename of the file, the name of the author, the date of creation
  and a description of what it does. In objects you may also want to include
  a list of the objects that make use of the code in this file if that is
  not too long, i.e. in an NPC the path to the room where the monster lives.

- All functions should be preceeded by a comment block, looking like the
  block in the example below. The four typical parts of that comment block
  are 'Function name', 'Description', 'Arguments' and 'Returns' where the
  latter two are optional. If necessary you may add other sections, though
  it is not likely you will need them.

- All code must be typed. This makes the code use less memory and it is
  easier to read.

- Use #pragma strict_types in all objects for extra type checking.
 
- The type declaration (including the other declarations, mentioned in
  'man access_classes') of a function should be on a separate line.

- Semicolons ';' and commas ',' should always be followed by a space if
  they do not terminate the line.

- Make use of comments in your code when needed. Even though the code
  eventually speaks for itself, it is always easier to have a description
  in English rather than having to wade through the actual statements to
  get some understanding.

- Only use the English language in variable names and comments. It is the
  'lingua franca' of the mud and people who do not speak your native
  language should also be able to understand what you mean. When you need
  an objectpointer to a shoe you might clone, using 'a' or 'sko' [Swedish]
  as variable name is not a good idea.

- There should always be an empty line between the end of one function
  and the comment header for the next function.

- Inside a function empty lines should be used to increase readability.
  It is a good practice to place empty lines between logically separate
  pieces of code.

COMMENT HEADER EXAMPLE
======================

A comment header will basically contain four subjects, if they are all
defined. First you have the name of the function, then a verbose description
of what it does. Next comes a description of all arguments if there are
any arguments to the function and you conclude with the what the function
returns unless it is of type void. In special cases, you may deem it
necessary to add additional fields, but these are the four general ones.

I do admit that it seems a little silly to add these kind of comment blocks
to all your create_room, create_weapon and alike obvious functions, but
it never hurts to be verbose in examples. However, I do counsel you to add
these kind of comment blocks to complex of otherwise special functions,
which use may not be clear at first glance. Remember that when you look at
a function six months after you wrote it, or if you look at a function that
someone else coded, it may help a lot to have some documentation.

/*
 * Function name: power
 * Description  : This function return the power of a given number.
 * Arguments    : int num - the number to compute the power of.
 * Returns      : int     - the power of the argument.
 */
public int
power(int num)
{
    return (num * num);
}

EXAMPLE FOLLOWING THE STANDARDS
===============================

/*
 * /doc/examples/obj/beer.c
 *
 * This is an example of a beer that can be drunk by people with an SS_CON
 * exceeding 48. If people try to swallow more than one beer at a time,
 * they will puke.
 *
 * It can be found lying about in the bank in /doc/examples/trade/bank.c
 *
 * /Mercade, January 27 1995
 */

/* Inherit the basic drink object. It contains many useful functions that
 * allow people to drink stuff.
 */
inherit "/std/drink";

#include <macros.h>
#include <stdproperties.h>

/*
 * Function name: create_drink
 * Description  : This function is called to create the object when it is
 *                cloned into memory. It gives the objects a name and sets
 *                some properties that make it a beer.
 */
public void
create_drink()
{
    /* Set the name 'beer' so people can call it that. The plural 'beers'
     * will automatically be generated.
     */
    set_name("beer");
    /* Set the adjective 'large'. The short description will automatically
     * be computed from the (first) name and all adjectives of the object
     * if none was set. Even if you manually set the short, you still have
     * to add adjectives to allow people to address this object as 'large
     * beer' too.
     */
    set_adj("large");
    /* Set the long description. This is what players will see if they
     * examine this beer.
     */
    set_long("It is a large beer and looks rather tasty.\n");

    /* A drink has to have a 'soft' amount, which is the volume of the
     * liquit in milliliters. The 'alco' amount is the amount of alcohol
     * in milliliters in the drink, which determines who can drink it and
     * how drunk they get from drinking it.
     */
    set_soft_amount(450);
    set_alco_amount( 16);

    /* Set some basic properties, in this case the combined weight and
     * volume of the drink in the glass or mug. Even though we did not
     * mention the form earlier, and people cannot call this a glass or
     * something, we include 300 grams and 100 milliliters for the glass.
     */
    add_prop(OBJ_I_VOLUME, 550);
    add_prop(OBJ_I_WEIGHT, 750);
}

/*
 * Function name: special_effect
 * Description  : This function is called when a player drinks this beer.
 *                Apart from the normal intoxication it allows us to do
 *                other mean things. In this case we make the player puke
 *                if he drinks more than one of these beers at the same
 *                time
 * Arguments    : int num - the number of beers the player swallows.
 */
public void
special_effect(int num)
{
    /* Only act if the player is gluttonous enough to drink more than one. */
    if (num > 1)
    {
	/* We make the player puke if he drinks two or more of these beers
	 * at the same time. *grin*
	 */
	write("My, you must be very thirsty.\n");
	say(QCTNAME(this_player()) + " must be very thirsty.\n");
	this_player()->command("puke");
    }
}
