Documentation is King

[Mac Write]

Originally Posted by 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):

PHP Code:

/**
 * 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]

Originally Posted by filburt1

Always document your code. There are no excuses.

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