Coding Style Guidelines

The following opinionated coding style guidelines go beyond what is enforced by clang-format. Please consider following them.

Doxygen

Function Plate Comments

This codebase is annotated with Doxygen plate comments in source files only (not in header files). Doxygen comments look like the following:

/**
 * @todo Documentation
 */

Note the double asterisk on the opening multi-line comment; this is required for Doxygen to recognize the comment. For documentation on the special commands (e.g. @todo, @note, @brief, etc.) found in Doxygen plate comments, visit this website: https://www.doxygen.nl/manual/commands.html.

Many deadstripped functions from the original codebase (unused or auto-inlined) are included in this decomp with a message in the the Doxygen plate comment indicating the known function size from the (usually USA rev 1) MetroWerks linker map:

/**
 * @todo Documentation
 * @note UNUSED Size: 00004C
 */

If you are decompiling a completely unused function that only survived in the DLL, what you have decompiled matches the UNUSED Size stated in the plate comment, and you are reasonably certain what you have written is correct, append (Matching by size) to the aforementioned comment to make it known that the function is as correct as we (currently) can guarantee. For example:

/**
 * @todo Documentation
 * @note UNUSED Size: 00004C (Matching by size)
 */

If the function also includes the comment // UNUSED FUNCTION in its body, feel free to remove it.

Member Single-Line Comments

Members of a struct/class or enum are documented in Doxygen with a decorated single-line comment syntax ///< (this is required for some reason). Consider the following stripped-down example from the codebase:

struct Collision
{
	Vector3f mNormal;         ///< Contact normal (i.e. line collision happens along).
	Vector3f mContactPoint;   ///< Contact point (between objects).
	RigidBody* mColliderBody; ///< Rigid body causing the collision.
};

Hand-Written Assembly

Operands following the instruction mnemonic should be aligned to at least two spaces after the longest instruction mnemonic in a block of code.

Unacceptable

psq_l fp2, 0x0000 (r31), 0, 0
lfs fp1, 0x0008 (r31)
ps_merge00 fp0, fp3, fp3

Acceptable

psq_l       fp2, 0x0000 (r31), 0, 0
lfs         fp1, 0x0008 (r31)
ps_merge00  fp0, fp3, fp3