Developer guidelines (Obsolete)

From Doomsday Wiki
Jump to: navigation, search

Sources

See libdeng2 code guidelines.

Coding style

1st Rule of Coding Style: When in doubt, go for readability.

2nd Rule of Coding Style: Consistency. Always be consistent in naming, ordering, documenting, commenting, and use of white space. This helps readability a lot.

3rd Rule of Coding Style: K.I.S.S. Simpler should always be preferred to complex, unless the need for complexity can be strongly justified.

Maximum preferred line width: 98 characters. However, readability is always more important than this limit.

Doxygen comments

Comments in Doxygen format describing the purpose, usage, parameters, return values, errors, and other information about functions is encouraged everywhere. All functions belonging to the public API (that are included in the headers in engine/api) should be documented in a Doxygen comment in the source file where the function is implemented.

For example:

/**
 * Does magical things to foobars.
 *
 * @param fooBar  Foobar to magic.
 *
 * @return  @c true, if the foobar is magicked.
 *          Otherwise @c false.
 */
boolean P_MagicFoobar(foobar_t *fooBar)
{
    int i = 0;
    ...( implementation )...

Game plugin headers

Always use the jdoom.h, jheretic.h, and jhexen.h high-level headers to include headers in game plugins. Due to problems with Xcode mistaking headers with the same name in different directories, the #include statements must contain enough context information (i.e., the directory, for instance "../../jheretic/include/") so that the correct header is included. Since this would be quite inconvenient if it had to be done with all #include statements, it is best to put all the #includes in the high-level headers and only #include those. For example:

#include "jheretic.h"

This way, all new headers are added or old ones are modified, the changes automatically affect all the relevant source files. Also, header precompiling can be used more efficiently.

Object-Orientedness

The Doomsday codebase should evolve towards more object-orientedness for increased flexibility and easier maintainability. This means that modules should be self-contained, global variables should be avoided, and function names should include the relevant class scope. For instance, a function that creates client mobjs might be called:

mobj_t *ClMobj_New(thid_t id);

(Naturally in C++ ClMobj would be a class.)

Constructors and destructors

Use the terms "new" and "delete" instead of "construct", "destruct", "destroy".

Do not

  • DO NOT use 1-based indexing for arrays. It is unnecessary, bug-inducing, and against convention.
  • DO NOT use arrays. Instead, use the STL containers (map/list/vector/etc.) that are best suited for the data.
  • DO NOT use meaningless words in identifier names. For instance, avoid using "manager". Every class manages something or the other, so naming it FooManager does not make it any more descriptive. Use a bit of imagination (and a dictionary/thesaurus) to come up with a word that describes what the class is or does.

Documentation

1st Rule of Documentation: DEW is the Right Place. All documentation should be here. Off-line copies, if needed, should be made from the wiki.

Version history

Earlier, version history has been recorded in version-specific release pages on the wiki. This practice should be discontinued. Instead, the automated build system will generate a changelog for each build. When it comes time to make a stable release, the most important changes are summarized for the release wiki page. It makes no sense to have a mile-long detailed list of all the things that have changed; instead, focus should be on providing an easy-to-digest summary of what is interesting from the user's point of view. Programmers who would like to know all the details can view the changelog in the Git repository.

Guidelines for documenting features

While/after implementing a feature, document it here into the wiki.