Dev:Coding Guidelines

Welcome to the Twilight Princess coding guidelines!

This document describes how to create and modify your Twilight Princess code properly. Although the standards and examples shown shouldn't be considered absolute you should try to generally follow all the standards which are described blow.

This document assumes coding in C/C++. If using a different language, please try to adopt these guidelines as best as you can.

Files & Directories

This section is about how you should name and order your project files and directories.

Generally you should always try to create and maintain a simple, meaningful and logical structure for your project files. A directory should primarily be used to group a set of files.

Naming rules

• Generally lower case (exceptions such as README.MD are permitted if meaningful, but try to avoid mixed capitalization)
• Use underscore instead of spaces
• Apply a meaningful filename (for example the class or namespace it represents)

General File Formatting

• UNIX-Like line endings LF (\n)
• Do not exceed a column width of 128 characters
• Use our clang-format configuration file (We recommend the use of VSCode with clang-format)

Variables & Functions

In order to help others find the symbol they need through IntelliSense (or other suggestion/autocomplete tool) we use the following naming schemes & rules:

Defines

• CAPS
• Must start with _

Namespace(s)

• Entirely lower case
• Underscore as seperator (no dashes etc.)
• Follow the file system structure (i.e. /source/module/sub-module/file.cpp => module::sub_module)

Local Variables

• Lower case camelCase
• Must not start with _

Functions

• PascalCase (upper case CamelCase)
• Always list parameters in the Header, this includes void (i.e. "bool func( void )" )

Classes & Structs

These rules apply to public and private space; If accessing within the class always use the this keyword when accessing a variable or function that isn't prefixed with "m_"!

• Class Name in PascalCase (upper case CamelCase)
• Struct Name either PascalCase or CAPS

Member Variables

• camelCase
• Must be prefixed with "_" (old m_ notation should be updated as it is obsolete)

Member Functions

• Upper case PascalCase (distinction from member variables)

Doxygen Documentation

Doxygen is a documentation generator, a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code. (Wikipedia)

Doxygen commands are used inside comment blocks.

Files

Documenting a file for Doxygen is fairly simple, each file must start with the following Doxygen commands in the following order:

1. Filename: @file <filename> The file command lets Doxygen know which file this comment block belongs to, it's required for Doxygen to consider the file for documentation! Otherwise it will be ignored and remains undocumented!
2. Brief: @brief <Brief description of the file> The brief description should contain a short text explaining what this file does and why it's there.
   • Optional: You can put a longer, more detailed description below the end of your brief description. The detailed description doesn't require an additional command like @description <desc>; instead it's being seperated via two newline (\n) chars, one before and the other after the description text.
3. Author[s]: @author <author> Every author should be listed in chronological order with the creator at the top.
4. Bug[s]: @bug <bug description> Like with the author tag, every bug should have its own line and @bug call, if there are no bugs known please state this exactly as follows: @bug No known bugs.
5. All commands should be packed to follow the same absolute indentation of 2.

Example:<syntaxhighlight lang="c++" line="1" start="1"> /** @file d_item.h

*	@brief Holds item specific functions and vars
*
*	@author AECX
*	@bug No known bugs
*/

</syntaxhighlight>

Symbols

By symbol we refer to functions, variables, enums, ... Everything with a human readable name that represents a data type or object is considered a symbol.

For documentation we have different rules for different types, since it's nearly impossible to cover every possible edge case you should remember to use common sense when documenting your symbols, however the following should always be taken into consideration:

Variables

Non-local variables should be documented with a type and description like @var <type> <desc>

Please do not document local variables in Doxygen style, instead use a trailing comment either behind or above your declaration.

Example:<syntaxhighlight lang="c++" start="1"> /**

* @var uint32_t The number of total frames since init 
*/

uint32_t m_TotalFrames;

...

// Counter through elements uint8_t i = 0; </syntaxhighlight>

Functions

Functions should be documented with a description, all parameters and a return description.

The @brief command takes a brief description as its first parameter and a optional detailed description as its second. Please split the detailed description with a line break like shown in the example.

Example:<syntaxhighlight lang="c++" start="1"> /**

*  @brief Runs when Link receives an item by opening a treasure chest
*  
*  Only runs for Demo items which is indicated by Link turning towards the
*  camera with the item floating above his hands
*
*  @param pos XYZ of the current TRES
*  @param item Item ID
*  @param unk3 Unknown
*  @param unk4 Unknown
*  @param unk5 Unknown
*  @param unk6 Unknown
*  @return Unknown use.
*/

s32 createItemForTrBoxDemo(const float pos[3], s32 item, s32 unk3, s32 unk4, const float unk5[3], const float unk6[3]); </syntaxhighlight>

Other

Generally you should apply the @brief command to virtually everything aside from local variables.

Feel free to use other Doxygen commands where you consider them useful.

Committing

Try to commit as often as possible and try to avoid unrelated changes in the same commit.

Your commit message should always be as short and precise as possible.