Commenting Guide

Types

Decription

A type comment should appear before the definition. Descriptions should be complete sentences.

• Class comments should describe what the class represents and what it can do.
• Struct comments should describe what is stored by the struct and any special functionality it has.
• Enum comments should describe what state it represents.
• Typedef comments should describe how the type is used.
• Delegate comments should describe what information is broadcast by that type.

/*
 * [Type description]
 */

Type Marker

A type name comment should appear before and after the class definition (in the .h) and before and after the definitions of the class's functions (in the .cpp). The type name should be used as the comment. Ex:

/* \/ ========= \/ *\
|  \/ UMyClass  \/  |
\* \/ ========= \/ */

class VOIDSINGER_API UMyClass : UObject
{
    GENERATED_BODY()

    [Code]
};

/* /\ ======== /\ *\
|  /\ UMyClass /\  |
\* /\ ======== /\ */

Functionality Category Markers

Category comments should appear before and after groups of functions and variables that all relate to a similar piece of functionality. These category markers should appear in both the .h and the .cpp. An example could be Voidsong Input Management. If in the .h, a new access specifier should always be placed after a new category starts, and members should be organized such that public comes first and then protected then private. In general, functions should appear before variables. Title case should always be used in category comments.

The Category specifier of UFUNCTIONs and UPROPERTYs should match these categories. Ex:

   /* ----------------- *\     
   \* \/ My Category \/ */  

public:

   UFUNCTION(BlueprintCallable, Category="My Category|My Subcategory")
   void MyFirstFunction();

   UPROPERTY(BlueprintReadWrite, Category="My Category")
   int MyFirstVar{ 0 };
                
protected:

   UFUNCTION()
   float MySecondFunction();

   UPROPERTY(BlueprintReadOnly, Category="My Category|My Subcategory")
   UObject* MySecondVar{ 0 };

private:

   UPROPERTY()
   bool bMyThirdVar{ 0 };

   /* /\ My Category /\ *\     
   \* ----------------- */

Functions

For more on commenting see Commenting Standards

Function Descriptions

A function comment should appear before the declaration and the definition of a function. Use Javadoc formatting for all function comments. Add a @param for each parameter. Add @return if a value is returned. Use title case for the parameter names, and descriptions should be complete sentences.

/*
 * [Function description - Say what the function does, not when this function is called]
 *
 * @param [Parameter Name] - [Parameter description - Describe what this parameter is used for]
 * @param [Parameter 2 Name] - [Parameter 2 description]
 *
 * @return - [Return description - Describe what is returned]
 */

Overload Comments

A function overload comment should appear before and after the overloaded functions. The comment should be the same as the function name. Ex:

// \/ MyFunction \/ //

void MyFunction(float Param1, bool bParam2);
void MyFunction(FVector Param3);

// /\ MyFunction  /\ //

Long Line Comments

A brief code description should appear over any line of code longer than the screen at 100% zoom or when it seems helpful. Descriptions should be complete sentences.

// [Briefly explain the logic]
MyVar = bMyBool ? MyOtherVar - (MyVar * MyVar).MyFunction(MyOtherOtherVar) : FMath::Max(MyOtherVar, 0.f);

Complex Getter Comments

Any large complicated segment of code obtaining a single value inside a chunk of logic should either be commented. Sentence case should be used. Ex:

//         |-------------------------------------- Get a variable ----------------------------------| + |-------- Get other function info --------| 
MyFunction(Cast<AGameModeClass>(UGameplayStatstics::GetGameMode())->GetAnActor()->GetAFloatVariable() + AObjectVariable->MyOtherFunction(AVarable));

or

float GetAVariable = Cast<AGameModeClass>(UGameplayStatstics::GetGameMode())->GetAnActor()->GetAFloatVariable();
float GetOtherFunctionInfo = AObjectVariable->MyOtherFunction(AVarable);
MyFunction(GetAVariable + GetOtherFunctionInfo);

Logic Chunk Comment

Any block of code working on a single thing that is longer than around half the screen should have a comment explaining what the code is doing. Sentence case should be used.

// \/ [Code description - Should be brief] \/ //

[Code]
[More code]
[Even more code]

// /\ [Code description] /\ //

Variables

All variables (including local variables) should have comments describing what they store. These comments should avoid mentioning how the variable is used in logic. Comments should be complete sentences.

//[Description]
int MyInt{ 0 };