Comments¶

Best Practices¶

See Clean Code: Comments rules
Use consistent and standard formats
- JSDoc
- SassDoc
- PhpDoc
Don't use comments to describe closing or ending code-blocks. Use proper indentation & code-folding for that.
Do not use comments as a substitute for poorly laid out code!
- Just for special cases where no matter how clearly laid out the code is, a reader simply would not understand

Do Not Use Comments To Reference Historical Context¶

Putting Jira Tasks, authors and incident logs within comments is typically bad practice. We can rely on git's version control history, Jira tasks, or documentation for that.

Incorrect

<mvt:comment>
    | * 2016-12-20: Used `Product_Load_Code` instead of `Product_Load_ID` (RM)
    | * 2016-10-01: Changed `temp_structure` from a structure to a local variable (JP)
    | * 2016-02-03: Changed `g.null` to `l.null` (LI)
</mvt:comment>
<mvt:do file="g.Module_Library_DB" name="l.success" value="Product_Load_Code('PRODUCT_CODE', l.product)" />

<mvt:assign name="l.temp_structure[1]:code" value="'ATTRIBUTE_CODE'" />
<mvt:assign name="l.temp_structure[1]:value" value="'OPTION_CODE'" />
<mvt:assign name="l.temp_structure[2]:code" value="'ATTRIBUTE_CODE'" />
<mvt:assign name="l.temp_structure[2]:value" value="'OPTION_CODE'" />

<mvt:do file="g.Module_Library_Utilities" name="l.success" value="Validate_Attributes_DetermineVariant( l.product, 0, l.temp_structure, miva_array_collapse( l.temp_structure ), l.null, l.null_count, l.variant_id )" />

Correct

<mvt:do file="g.Module_Library_DB" name="l.success" value="Product_Load_Code( 'PRODUCT_CODE', l.product )" />

<mvt:assign name="l.temp_structure[1]:code"     value="'ATTRIBUTE_CODE'" />
<mvt:assign name="l.temp_structure[1]:value"    value="'OPTION_CODE'" />
<mvt:assign name="l.temp_structure[2]:code"     value="'ATTRIBUTE_CODE'" />
<mvt:assign name="l.temp_structure[2]:value"    value="'OPTION_CODE'" />

<mvt:do file="g.Module_Library_Utilities" name="l.success" value="Validate_Attributes_DetermineVariant( l.product, 0, l.temp_structure, miva_array_collapse( l.temp_structure ), l.null, l.null_count, l.variant_id )" />

Use Comments To Explain Areas The Code Cannot¶

Comments should be used sparingly to explain business logic where code isn't self explanatory.

MVT¶

Incorrect

<mvt:comment>
|
|   Load all pages
|
</mvt:comment>
<mvt:do file="g.Module_Feature_TUI_DB" name="l.success" value="PageList_Load_All( l.settings:pages )" />

<mvt:comment>
|
|   Iterate over pages
|
</mvt:comment>
<mvt:foreach iterator="page" array="pages">
    <mvt:comment>
    |
    |   Page Title
    |
    </mvt:comment>
    <mvt:assign name="l.settings:page:title" value="''" />

    <mvt:comment>
    |
    |   Update page title
    |
    </mvt:comment>
    <mvt:do file="g.Module_Feature_TUI_DB" name="l.success" value="Page_Update( l.settings:page )" />

    <mvt:comment>
    |
    |   Remove ALL meta fields
    |
    </mvt:comment>
    <mvt:do file="g.Module_Root $ '/modules/component/cmp-mv-prodctgy-meta.mvc'" name="l.success" value="METAValue_Delete_Page_All( l.settings:page:id )" />
</mvt:foreach>

Correct

<mvt:comment>
|
|   Load all pages to remove the page title
|   and delete the meta values for the page
|
</mvt:comment>
<mvt:do file="g.Module_Feature_TUI_DB" name="l.success" value="PageList_Load_All( l.settings:pages )" />

<mvt:foreach iterator="page" array="pages">
    <mvt:assign name="l.settings:page:title" value="''" />

    <mvt:do file="g.Module_Feature_TUI_DB" name="l.success" value="Page_Update( l.settings:page )" />

    <mvt:do file="g.Module_Root $ '/modules/component/cmp-mv-prodctgy-meta.mvc'" name="l.success" value="METAValue_Delete_Page_All( l.settings:page:id )" />
</mvt:foreach>

Comment Formats¶

Use the following comment formats.

CSS Comments¶

Use SassDoc comments.

Comments that define sections:

/* Example Section
=========================================== */

Standard comments:

/* Example Comment */

JavaScript Comments¶

Use JSDoc formatted comments.

Single Line

// Example Comment

Multi Line

/**
* Multiline
* Example
*
* Multiline example comment
*/

MVT Comments¶

Incorrect

<mvt:comment> This is my comment </mvt:comment>

<mvt:comment>
    This is my comment
</mvt:comment>

Correct

<mvt:comment>
|
|   This is a valid comment
|
</mvt:comment>

<mvt:comment>
|
|   This is also a valid comment that
|   May need to go to 2 lines because
|   I have other details to discuss here.
|
</mvt:comment>

PHP Comments¶

Use PhpDoc formatted comments.

<?php
/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to
 * total. Returns total.
 *
 * This function can also be implemented using array_reduce();
 *
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}