CS:commenting

Commenting

 * One of //__THE MOST IMPORTANT__// things to remember while writing code is that you //must comment// your code!!!! **

The code you write will be viewed, modified, copied, scrutinized, utilized, and reincarnated by dozens - potentially hundreds - of developers from around the world.

Comments **must** be:

* Well-written and descriptive, but brief. * Written in plain English.

Comments //should// be: * Dated using the date format specified in the Locale Standards section. Example: 05-APR-2010 * Signed at the end with your sandbox username between less-than (<) and greater than (>) symbols. Example:   * Describe parameter and function usage, as well as usage information (where applicable e.g. functions and classes)

Comments must **not**: * Begin with the hashbang (#) character * Exceed the maximum formatting

Comment Formatting
When writing a comment that will fit on three or fewer lines, please use the double-forward-slash method. Example:

When writing code that will be in excess of three lines, please use a comment blocks. The format for such should adhere to the following standard:

When appending to someone else's comments, add yours BELOW theirs, so that the comments read as a timeline. Do not edit the text of existing comments (including your own) for any reason, including typos. If the comment is incorrect, or is no longer applicable in any part, remove it and replace it with your own. If the updated comment area will exceed three lines, convert the old comments to a comment block as described above, and append yours beginning with a new line. For example:

Adding additional lines would then be cause for conversion: