-
Notifications
You must be signed in to change notification settings - Fork 0
Commenting Guide
##Blueprint
##C++
A function comment should appear before the declaration and the definition of a function. Use Javadoc formatting for all function comments. Add another @param for each parameter. Add @return if a value is returned. Use title case for the parameter names, and sentence case for the descriptions.
/*
* [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]
*/
A function overload comment should appear before and after the overloaded functions. Title case should be used.
// \/ [Function Name] \/ /
[Function Overload 1]
[Functions Overload 2]
// /\ Function Name /\ /
A brief code description should appear over any line of code longer than the screen at 100% zoom or when it seems helpful. Sentence case should be used.
// [Description - Should briefly explain the logic]
Any large complicated segment of code obtaining a single value inside a chunk of logic should either be commented (sentence case should be used)
// |------------ [Description of this section] ---------------| |-------- [Description of this other section] --------|
or split up into variables.
VarType ThisSection = blah
VarType ThisOtherSection = blahblah
As an example, you could do
// |-------------------------------------- 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);
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] /\ /
Variable comments should appear before the declaration of a variable. Local variables should also be commented. Sentence case should be used.
//[Description - Should describe what the variable stores, not how it is used (in general)]
A class 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). Title case should be used in class name comments.
/* \/ ============ \/ *\
| \/ [Class Name] \/ |
\* \/ ============ \/ */
[Code]
/* /\ ============ /\ *\
| /\ [Class Name] /\ |
\* /\ ============ /\ */
A class comment should appear before the class definition. Sentence case should be used.
/*
* [Class description - Should explain what this class is used for/does]
*/
Category comments should appear before and after functions and variables that belong in that category. Use categories to organize functions and variables that work together to complete a certain task. An example could be Voidsong Input Management. If in the .h, a new access specifier should always be placed after a new category starts. Title case should always be used in category comments.
/* ------------------- *\
\* \/ Category Name \/ */
[Access Specifier (if in .h)]:
[Code]
/* /\ Category Name /\ *\
\* ------------------- */
Delegate comments should appear above their definition.
//[Description - Explain what information is broadcasted]
Typedef comments should appear above their definition.
///[Description - Explain what kind of information is stored by this type]
A struct name comment should appear before and after the struct definition (including any hash functions).
/* \/ ============= \/ *\
| \/ [Struct Name] \/ |
\* \/ ============= \/ */
[Code]
/* /\ ============= /\ *\
| /\ [Struct Name] /\ |
\* /\ ============= /\ */
A struct comment should appear before the struct definition.
/**
* [Description - Explain what information is stored and any special functionality]
*/
An enum name comment should appear before and after the enum definition.
/* \/ =========== \/ *\
| \/ [Enum Name] \/ |
\* \/ =========== \/ */
[Code]
/* /\ =========== /\ *\
| /\ [Enum Name] /\ |
\* /\ =========== /\ */
An enum comment should appear before the enum definition.
/**
* [Description - Should explain what information the enum carries]
*/