Skip to content

Comments#

Best Practices#

  • See Clean Code: Comments rules
  • Use consistent and standard formats
  • 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 `s.null` (SS)
</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.basketoptions, l.basketoption_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.basketoptions, l.basketoption_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#

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;
}