There is a general way of commenting that is taught at schools and universities (at least here). It works basically like this:
At the top of each program, you write your name, the date, the name of the script/program, and what it's suppossed to do. You may want to explain what it's for, why you wrote it, how to read it, and any conventions you used (i.e. special use of global variables).
Before each function, you have a header that has the name of the function, it's purpose, it's parameters, and it's return. This is the stadard "javadoc" way of commenting.
Any other "in-line" comments should come in as you go along to clarify for the reader of the code.
All in all, your scripts should look like this:
Code: Select all
<?php
/************************
March 20, 2005 *
This is wrtten to show *
Ambush Commander proper *
commenting conventions *
*************************/
//declare all the variables
$var1; //you never actually want to use names like this
$var2;
/****************************
@name: add
@param: $var1, $var2
@return: $sum, integer
@desc: This function takes two integer values and adds them
*****************************/
function add($var1, $var2){
$sum;
$sum = $var1 + $var2;
return $sum;
}
//this adds 2 and 3 and stores it in var1
var1 = add(2,3);
//this adds 4 and 5 and stores it in var2
$var2 = add(4,5);
//this adds var1 and var2 and outputs it
echo add(var1,var2);
?>
Hope this helps!