Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (95 loc) · 5.07 KB

CONTRIBUTING.md

File metadata and controls

127 lines (95 loc) · 5.07 KB

Contributing

Code Guidelines

General

  • Lines should not exceed 100 characters, these can be split into multiple lines.
  • Use nullptr instead of 0 when assigning / comparing a pointer (unless strictly necessary).
  • Use the .cpp/.hpp extension for C++ files, the .c/.h extension for C files and the .s extension for ASM files.
  • The preferred indentation style is 1TBS/OTBS.
  • Empty code blocks should only take one line.

Nonmatching Code

  • If your code does not match, use the NONMATCHING macro, and explain in a comment why it does not match.
  • The aforementioned macro can also be used to offer alternative, better-looking code.

Headers

  • Use forward-declared types when possible.

  • At the top of every header place:

    #pragma once

Includes

  • For includes use:

    #include <...>

    (These are relative to the include folder.)

Names

  • Names for known symbols should match exactly, including typos.
  • Member variables must be prefixed with m (and p if they're a pointer).
  • Static member variables must be prefixed with s (and p if they're a pointer).
  • The above rule can be ignored if the existing symbol differs.
  • Functions with no known symbol must use camelCase.

Types

  • Pointer/reference types must have the asterisk/ampersand near the variable name.
  • Use C style casts to cast a type to another.

Constants

  • Constants with a heavy impact on the game must be declared and used properly. If such a constant appears in more than one compilation unit, it must be placed in constants/game_constants.h. Else, place it in the correct header file.
  • Japanese text strings must be placed in constants/sjis_constants.h.

Enumerations

  • Unless a cracked symbol says otherwise, the following conventions apply:
    • The enumeration tag should be all uppercase with the suffix _e.
    • Enumeration identifiers should be all uppercase.
    • Global enum identifiers must be prefixed, while for class enum identifiers it's optional (do it, for example, if it increases readability or prevents confusion).

Comments

  • Code comments should begin with an uppercase letter and usually not end in a period.
  • Place comments that could not have been in the original code between square brackets. Examples include:
    • // Parameters that can be set to configure the behaviour of the base. [These are the sprite data fields in Reggie].
    • // [TODO: is this an int or an enum?]

Classes

  • When referencing a class member, do not use this-> unless required for compilation.

  • Try to use constructor initializers as much as possible.

  • Class members must be placed in the following order:

    • Nested Classes/Structures/Enumerations
    • Functions (place static ones last)
    • Variables (place static ones last)
    • Friends

  • Functions for classes must be placed in the following order:

    • Constructor
    • Destructor (unless virtual)
    • Operators (unless virtual)
    • Virtual Functions
    • Member Functions (place static ones last)

  • Set appropriate access modifiers for each member. Within each category listed above, place the entries in the following order:

    • Public
    • Protected
    • Private

  • If the virtual functions do not follow the ordering conventions, the above rules can be ignored.

Documentation

Doxygen is being used for generating documentation:

  • Use @ to begin Doxygen commands.

  • In general, always start a documentation comment with an uppercase letter and terminate it with a period. Try to refer to variables/arguments using articles and try to use the third person when documenting functions. See below for examples.

  • For functions which require a decently long explanation, and/or documentation for the parameters and return values, use multiline comments, like this:

    /**
 * @brief Instantiates a base under a parent base.
 *
 * @param profName The profile name.
 * @param parent The base's parent.
 * @param param The base's parameters.
 * @param groupType The base's group type.
 * @return A pointer to the instantiated base.
 */

  • If the functionality is rather obvious, please still write a short comment. You can use single-line comments:

    /// @brief Requests deletion of the base.
void deleteRequest();

    Or, if it looks better, you may also use inline comments:

    virtual int create(); ///< Creates the base.
virtual int preCreate(); ///< Code to be executed before create().
virtual void postCreate(MAIN_STATE_e state); ///< Code to be executed after create().

  • If no official symbol has been cracked for a class or a function, report this information using the @unofficial command. For unknown class names, adding the note to each member function is not necessary.

  • If something in the code is confirmed to be unused, report this information using the @unused command.

  • Do not document inline getters/setters unless their logic is complex, document the corresponding variables instead.

  • Documenting not yet decompiled code is not necessary.