Documentation is King

[filburt1]

Always document your code. There are no excuses.

I strongly recommend using PHPDoc format which is essentially the same as popular Javadoc. A sample (a vBMS port I'm working on):

/**
* Displays an error if a required field in a form was missing or empty.
*
* Searches through $fields, an associative array of form element names mapped
* to human-readable names, for elements that are not present in $_POST or $_GET.
* If one or more of the elements is missing, an informative error is displayed.
*
* @param fields array of fields for which to check
*
* @return void
*/
function vbms_checkrequiredfields($fields)
{
$missing = array();

foreach ($fields as $name => $humanreadable)
{
if (empty($_POST[$name]) and empty($_POST[$name]))
{
array_push($missing, $humanreadable);
}
}

if (!empty($missing))
{
vbms_scrubhtml($missing);
foreach ($missing as $key => $value)
{
$missing[$key] = "<li>$value</li>";
}
$missing = implode("\n", $missing);

eval(print_standard_error("error_vbms_missingfields"));
}
}

[Mac Write]

Always document your code. There are no excuses.

I strongly recommend using PHPDoc format which is essentially the same as popular Javadoc. A sample (a vBMS port I'm working on):

/**
* Displays an error if a required field in a form was missing or empty.
*
* Searches through $fields, an associative array of form element names mapped
* to human-readable names, for elements that are not present in $_POST or $_GET.
* If one or more of the elements is missing, an informative error is displayed.
*
* @param fields array of fields for which to check
*
* @return void
*/
function vbms_checkrequiredfields($fields)
{
$missing = array();

foreach ($fields as $name => $humanreadable)
{
if (empty($_POST[$name]) and empty($_POST[$name]))
{
array_push($missing, $humanreadable);
}
}

if (!empty($missing))
{
vbms_scrubhtml($missing);
foreach ($missing as $key => $value)
{
$missing[$key] = "<li>$value</li>";
}
$missing = implode("\n", $missing);

eval(print_standard_error("error_vbms_missingfields"));
}
}

What's the best way to document changes you make in Templates?

<!-- Comment -->
looks ugly. I would rather do

//comment
//comment

[AlexanderT]

For templates, if really necessary, I would keep documentation of changes in a seperate file. <!-- Comments --> a) looks ugly, as you said yourself. b) can give a potential hacker more information than I'd like to share. c) increases load times.

[splooge]

Always document your code. There are no excuses.

It was hard to write ... it should be hard to read!