Dev:Coding Guidelines

From Twilight Princess Wiki
Jump to navigation Jump to search

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)

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:

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

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:

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

...

// Counter through elements
uint8_t i = 0;

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:

/**
 *  @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]);

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.