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.

function addUserToDatabase(userName, userAge)

1. They should provide an outline of the function.
2. They should explain what the code is doing without restating the code itself.
3. 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.
4. 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;
}

1. what the function does (not how it does it)
2. the role of each input value
3. any assumptions the function makes about the input values
4. 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

1. the name of the file
2. the author's name
3. Copyright statement
4. a brief statement of the contents of the file
5. the date the file was created
6. 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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

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.