Commenting Guide

Commenting

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 /\ *\     
   \* ----------------- */