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

These standards are mandatory for all new code in the game.

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. When wrapping long lines, also use 4
  spaces as indent.

- 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 only
  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.

- Always use #pragma strict_types in your code, this pragma will cause an error
  when you try to load an object with one or more functions having no return
  type.

- 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, but don't overdo it. Even
  though code eventually speaks for itself, a description in plain English is
  often very helpful. Code completely without comments is often hard to read,
  but too heavily commented code isn't much better, especially if the comments
  are not kept up-to-date with changes to the code. Too much commenting may
  mean that the code is over-complicated. A good rule is to comment everything
  that needs it, but write code that doesn't need much of it. And when you do
  comment rather comment why something is done than how.

- 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 object
  pointer 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.

- When continuing long strings on another line, the '+' should come at the end
  of the preceding line, not at the beginning of the new line.

- Avoid excessive use of preprocessor macros. Macros should always serve to
  increase the readability and portability of code, not just to save a few
  typing strokes.

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
 */

inherit "/std/drink";

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

/*
 * Function name: create_drink
 * Description  : Constructor to configure the drink when it is created.
 */
public void
create_drink()
{
    set_name("beer");
    set_adj("large");

    set_long("It is a large beer and looks rather tasty.\n");

    set_soft_amount(450);
    set_alco_amount(16);

    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");
    }
}
