_Commenting Standards

Code Commenting Standards

Commenting your code is like cleaning your bathroom---you never want to do it, but it really does create a more pleasant experience for you and your guests. Below is a list of code comment requirements for all developers writing code at Lead Liaison.

We use phpDocumentor tags for all code commenting. Reference http://www.phpdoc.org/ for a manual of all code commenting tags to use. The information below defines five categories of commenting required for all developers. The five categories are code, inline, function, file header and additional commenting. Use phpDocumentor tags for each of the five categories. Read the "phpDocumentor Quickstart" guide to get started.

Code Commenting - This refers to writing descriptive variable names that are self explanatory. This is a minimalist form of commenting, and looks like the below. Without any additional information, you can tell that the function will add a user's name and age to a database.

function addUserToDatabase(userName, userAge)

Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well. This is the most basic form of commenting.

They should provide an outline of the function.
They should explain what the code is doing without restating the code itself.
They are necessary only when it is not obvious what the code is doing. To determine "obviousness", ask yourself the question "If I had never seen this code before, or even hadn't seen it for a week, how long would it take me to determine what this section does?" If the answer is anything longer than 1 minute, include a comment.
They should appear at the closing brace of long blocks to help the reader determine which opening brace it is paired up with.

function calculateHitPoints(cUser) {
    var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength    // subtract user size : small = 1, medium = 2, large = 3
    var nDamage = (nStrength * 3) * cUser.nSize;
    return cUser.nCurrentHitPoints * nDamage;
}

Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function. This includes parameters, return values, and any logic quirks or decisions that were made:

what the function does (not how it does it)
the role of each input value
any assumptions the function makes about the input values
any guarantees the function makes about its output value

/*
 * Summary:      Calculate hitpoints after attack using formula
 *               new = current * ((enemyStrength*3) * size)
 * Parameters:   cUser: object containing hero's stats
 * Return:       Boolean indicating life or death
 */
function calculateHitPoints(cUser) {
    something
} // end calculateHitPoints

File Header Commenting - Comments that refer to an entire page or top level object (class file) fall into this category.

the name of the file
the author's name
Copyright statement
a brief statement of the contents of the file
the date the file was created
the date the file was last modified

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title : Name of file
Author: Name <email address>
Copyright: (c) 2002, Gregory Beaver
Description : Here's a summary of what this file does
Created : July 18th, 2011
Modified : September 29th, 2012
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

Additional comments to benefit a team:

Here are some common comments you can feel comfortable using in your code:

    TODO: This key phrase signifies what needs to be accomplished and should be placed on the line where the future code should go.

    BUG / FIX: Document a specific bug, or a fix for a bug, and place the comment above the line it pertains to. If you use bug tracking software, include the ID of the bug, so you can always track where it occurred and how you fixed it.

    TEAMNAME: This comment is usually different wherever you work, but is used to call attention to a certain programmer or programming team. For example, you may want to let the Artificial Intelligence team know why you made a certain decision and so you would use this type of comment to alert them.

Resources:

Generating documentation from comments: http://www.freeopenbook.com/php-hacks/phphks-CHP-8-SECT-8.html 
PHPDocumentor: http://www.phpdoc.org/