vb.org Archive

vb.org Archive (https://vborg.vbsupport.ru/index.php)
-   General Articles (https://vborg.vbsupport.ru/forumdisplay.php?f=189)
-   -   Documentation is King (https://vborg.vbsupport.ru/showthread.php?t=56370)

filburt1 08-19-2003 10:00 PM
Documentation is King
 
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"));
    }
} 

Mac Write 04-12-2004 02:47 AM
Quote:
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 04-12-2004 06:51 AM
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 04-29-2004 07:54 PM
Quote:
Originally Posted by filburt1
Always document your code. There are no excuses.
It was hard to write ... it should be hard to read!


All times are GMT. The time now is 04:06 AM.

Powered by vBulletin® Version 3.8.12 by vBS
Copyright ©2000 - 2025, vBulletin Solutions Inc.

X vBulletin 3.8.12 by vBS Debug Information
  • Page Generation 0.01158 seconds
  • Memory Usage 1,736KB
  • Queries Executed 10 (?)
More Information
Template Usage:
  • (1)ad_footer_end
  • (1)ad_footer_start
  • (1)ad_header_end
  • (1)ad_header_logo
  • (1)ad_navbar_below
  • (2)bbcode_php_printable
  • (2)bbcode_quote_printable
  • (1)footer
  • (1)gobutton
  • (1)header
  • (1)headinclude
  • (6)option
  • (1)post_thanks_navbar_search
  • (1)printthread
  • (4)printthreadbit
  • (1)spacer_close
  • (1)spacer_open 
Phrase Groups Available:
  • global
  • postbit
  • showthread
Included Files:
  • ./printthread.php
  • ./global.php
  • ./includes/init.php
  • ./includes/class_core.php
  • ./includes/config.php
  • ./includes/functions.php
  • ./includes/class_hook.php
  • ./includes/modsystem_functions.php
  • ./includes/class_bbcode_alt.php
  • ./includes/class_bbcode.php
  • ./includes/functions_bigthree.php 
Hooks Called:
  • init_startup
  • init_startup_session_setup_start
  • init_startup_session_setup_complete
  • cache_permissions
  • fetch_threadinfo_query
  • fetch_threadinfo
  • fetch_foruminfo
  • style_fetch
  • cache_templates
  • global_start
  • parse_templates
  • global_setup_complete
  • printthread_start
  • bbcode_fetch_tags
  • bbcode_create
  • bbcode_parse_start
  • bbcode_parse_complete_precache
  • bbcode_parse_complete
  • printthread_post
  • printthread_complete