From MapbenderWiki

Layout

• source code is best documented using NaturalDocs.
• indent comments with its corresponding code (don't indent if you deactivate code via comments)

for () {
    for () {
        // this line is a comment
//      echo "this line is deactivated";
    }
}

• set off each comment with at least one blank line

bad JavaScript

alert('Hello world');
// yet another 'Hello world'
alert('Hello world');

good JavaScript

alert('Hello world');

// yet another 'Hello world'
alert('Hello world');

• don't use endline comments; prepare the reader about what follows: comment precedes code it describes

bad JavaScript

var someString = 'Hello world'; // endline comment

good JavaScript

// comment before statements
var someString = 'Hello world';

General advice

• performance is not a good reason to avoid commenting (maybe use a packer for JS code)
• code should be readable itself, documentation comes second (focus on why, not on how)
• don't document bad code, rewrite it (if you ask yourself "is this tricky?", it is)
• if tricky code is unavoidable, document it (focus on why, and why not otherwise)
• justify violations of good programming style (otherwise other developers might change it)
• avoid comments that just repeat the code (there's no virtue in excessive commenting)
• avoid abbreviations
• differentiate between major and minor comments (suggestion: minor code preceded by three dots: ... some minor comment)
• use markers like TODO in Eclipse
• comment anything that gets around an error or an undocumented feature in a language or an environment (like Internet Explorer and Firefox differences)
• comment units of numeric data (km, pixel etc.)
• document the source of algorithms used
• use pseudocode programming process to reduce commenting time (write comments first, afterwards add the corresponding code)