Revision history for CodingGuidelinesHowto


Revision [23458]

Last edited on 2016-05-20 07:38:48 by CoreyAvis [Replaces old-style internal links with new pipe-split links.]
Additions:
[[WikkaHowto | Wikka "Howto" Pages]]
~-[[DocumentingCodeHowto | Code Documentation Tutorial]]
~As we can read in the PHP docs about [[PHP:include | include]]: "require() and include() are identical in every way except how they handle failure. include() produces a Warning while require() results in a Fatal Error." ---
~##include## and ##require## are **//statements//**, not functions. The parentheses (as in the little quote above) are optional in PHP. (According to the [[PHP:include | include docs]]: "Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.") ---
Deletions:
[[WikkaHowto Wikka "Howto" Pages]]
~-[[DocumentingCodeHowto Code Documentation Tutorial]]
~As we can read in the PHP docs about [[PHP:include include]]: "require() and include() are identical in every way except how they handle failure. include() produces a Warning while require() results in a Fatal Error." ---
~##include## and ##require## are **//statements//**, not functions. The parentheses (as in the little quote above) are optional in PHP. (According to the [[PHP:include include docs]]: "Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.") ---

Revision [21238]

Edited on 2010-07-06 16:40:45 by CoreyAvis [Gave example were needed to help.]
Additions:
if ($page["tag"] != $tag) return false;
else return true;
if ($page["tag"] == $tag) return true;
else return false;
Deletions:
need example
need example

Revision [21221]

Edited on 2010-06-28 13:22:50 by YaVerOt [spellchecking.]
Additions:
**{{color c="green" text="recommended:"}}** (used variable substitutes should be explained in a comment afterwards)
~~-(float), (double), (real) - cast to float; preferred form (float)
Multi line comments should have the ##/* ... */## form or a number of #-chars. The first and last line in a comment should really stand out by having a number of repeating * or # characters. Within the multi-line comment each line should start with either the * character or the # character, depending.
Single line comments must have a open line before the comment. Single line comments can either be the ##""//""## notion followed by a space. It is also possible to use 3 consecutive lines with the # character where the 1 and 3rd lines does not have any content. The #-character must be followed by a space. Single line comments must follow the indentation of the surrounding code.
~-Follow the coding conventions of the package itself, //even if they do not correspond to Wikka coding guidelines//: you don't want to re-code the whole thing, and code with a mix of conventions used is hard to read.
Many editors can help implementing some of the coding standards and not only enforce consistency this way, but save you a bunch of time as well. A good "programmer's" editor will have settings to enforce line endings (when creating a new file and/or when saving a file) and for gettng rid of spurious white space at the end of lines (as a function, or as a setting to automatically do this when saving a file).
Deletions:
**{{color c="green" text="recommended:"}}** (used variable substitues should be explained in a comment afterwards)
~~-(float), (double), (real) - cast to float; prefered form (float)
Multi line comments should have the ##/* ... */## form or a number of #-chars. The first and last line in a comment should really stand out by having a number of repeating * or # characters. Within the multi line comment each line should start with either the * character or the # character, depending.
Single line comments must have a open line before the comment. Single line comments can either be the ##""//""## notion followed by a space. It is also possible to use 3 concecutive lines with the # character where the 1 and 3rd lines does not have any content. The #-character must be followed by a space. Single line comments must follow the indentation of the surrounding code.
~-Follow the coding conventions of the package itself, //even if they do not correspond to Wikka coding guidelines//: you don't want to re-code the whole thing, and code with a mix of conventions used is hardd to read.
Many editors can help implementing some of the coding standards and not only enforce consistency this way, but save you a bunch of time as well. A good "programmer's" editor will have settings to enforce line endings (when creating a new file and/or when saving a file) and for gettng rid of spurious white space at the end of lines (as a function, or as a settnig to automatically do this when saving a file).

Revision [21218]

Edited on 2010-06-23 01:21:06 by GeorgePetsagourakis [fixed some tabbing]
Additions:
foo($squares, $triangles);
foo($i, $j);
Deletions:
foo($squares, $triangles);
foo($i, $j);

Revision [20725]

Edited on 2009-06-18 01:06:28 by BrianKoontz [Added page to Development category]
Additions:
CategoryDevelopment

Revision [19329]

Edited on 2008-01-28 00:15:16 by DarTar [Modified links pointing to docs server]

No Differences

Revision [17388]

Edited on 2007-08-10 04:04:27 by DarTar [fixing layout]
Additions:
Multi line comments should have the ##/* ... */## form or a number of #-chars. The first and last line in a comment should really stand out by having a number of repeating * or # characters. Within the multi line comment each line should start with either the * character or the # character, depending.
Single line comments must have a open line before the comment. Single line comments can either be the ##""//""## notion followed by a space. It is also possible to use 3 concecutive lines with the # character where the 1 and 3rd lines does not have any content. The #-character must be followed by a space. Single line comments must follow the indentation of the surrounding code.
Deletions:
Multi line comments should have the /* ... */ form or a number of #-chars. The first and last line in a comment should really stand out by having a number of repeating * or # characters. Within the multi line comment each line should start with either the * character or the # character, depending.
Single line comments must have a open line before the comment. Single line comments can either be the // notion followed by a space. It is also possible to use 3 concecutive lines with the # character where the 1 and 3rd lines does not have any content. The #-character must be followed by a space. Single line comments must follow the indentation of the surrounding code.

Revision [17386]

Edited on 2007-08-09 22:15:32 by RubenOlsen [fixing layout]
Additions:
~& A_lot_of_under_scores_are_hard_to_read - we should also allow camelCased variable names as long as the name begins with a lower-case letter
~& RubenOlsen
~& We should have a better example as single quotes are allowed i HTML, thue reducing the need for escaping anything.
~& RubenOlsen
##################################################################################
##################################################################################
##################################################################################
##################################################################################
##################################################################################
##################################################################################
Deletions:
#########################################
#########################################
#########################################
#########################################
#########################################
#########################################

Revision [17385]

Edited on 2007-08-09 22:05:46 by RubenOlsen [fixing layout]
Additions:
if (($fh = fopen($rssFile,'w')) === FALSE)
if (FALSE == $fh)
==Do not short circuit logical tests==
Short circuiting will sooner or later introduce logical error in your code. Avoid this at all costs by using the correct amount of parantheses.
if ( 8 == $i || 10 == $i && 12 == $j )
if ( (8 == $i) || (10 == $i && 12 == $j) )
if (FALSE === ($fh = fopen($rssFile,'w')))
if (FALSE == $fh)
if ($inputNubmer == 12)
if (12 == $inputNumber)
== Use switch structures rather than nested if-then-else ==
Switch structures enhances readability in your code.
if ($i == 0)
echo "i equals 0";
} elseif ($i == 1) {
echo "i equals 1";
} elseif ($i == 2) {
echo "i equals 2";
switch ($i)
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
switch ($food)
case "apple":
echo "food is apple";
break;
case "bar":
echo "food is bar";
break;
case "cake":
echo "food is cake";
break;
do
} while (condition)
===Comments===
==Re-write complex code instead of commenting==
If the code is so complex that it requires lengthy explanations, then the code should be re-written. Comments should only be used to explain the logical flow of the program - and the code it self should be clear enough to be self documenting.
==Comments should be readable and easy to spot==
The content of the comment is important, make it readable! The content of a comment must not exceed 80 characters per line.
Use comments to group various parts of the code.
Multi line comments should have the /* ... */ form or a number of #-chars. The first and last line in a comment should really stand out by having a number of repeating * or # characters. Within the multi line comment each line should start with either the * character or the # character, depending.
Single line comments must have a open line before the comment. Single line comments can either be the // notion followed by a space. It is also possible to use 3 concecutive lines with the # character where the 1 and 3rd lines does not have any content. The #-character must be followed by a space. Single line comments must follow the indentation of the surrounding code.
End of line comments should be indicated by the #-character.
/* ****************************************************
*
* Copyright (C) 2002, 2003 Hendrik Mans <[email protected]>
* Copyright (C) 2004, 2005 Jason Tourtelotte <[email protected]>
* Copyright (C) 2006 Wikka Development Team <[email protected]>
*
****************************************************** */
#########################################
# Copyright (C) 2002, 2003 Hendrik Mans <[email protected]>
# Copyright (C) 2004, 2005 Jason Tourtelotte <[email protected]>
# Copyright (C) 2006 Wikka Development Team <[email protected]>
#########################################
#########################################
# Initalize variables
#########################################
$name = ""; # The users name
$address = "" ; # The users address
#########################################
# Main routine
#########################################
// Grab HTTP GET
$name = $_GET['username'];
$address = $_GET['address'];
// Print out some information
print "The name is $name";
if ($name == "RubenOlsen")
// Friendly greeting is in place
print "Hello Ruben - have a nice day!";
// Ordinary greeting
print "Hello $name - now, get to work!";
#
# Print out concatenated information
#
print "Name and address $name, $address";
/* Copyright (C) 2002, 2003 Hendrik Mans <[email protected]>
Copyright (C) 2004, 2005 Jason Tourtelotte <[email protected]>
Copyright (C) 2006 Wikka Development Team <[email protected]> */
//Initialize variables
$name = "";
$address = "" ;
//Grab HTTP GET
$name = $_GET['username'];
$address = $_GET['address'];
print "The name is $name";//Print out some information
if ($name == "RubenOlsen")
//Friendly greeting is in place
print "Hello Ruben - have a nice day!";
print "Hello $name - now, get to work!";//Ordinary greeting
# Print out concatenated information
print "Name and address $name, $address";
==Wikka specific comments==
(need more info regarding the @input, @output, etc)
==PHP Doc==
(need more info)
Deletions:
if (($fh = fopen($rssFile,'w')) === FALSE) {
if (FALSE == $fh) {
if (FALSE === ($fh = fopen($rssFile,'w'))) {
if (FALSE == $fh) {
if ($inputNubmer == 12) {
if (12 == $inputNumber) {

Revision [17384]

Edited on 2007-08-09 21:16:47 by RubenOlsen [fixing layout]
Additions:
===Conditionals===
==Complex conditionals must be avoided==
By introducing temporary boolean variables to expressions the code will be much easier to maintain.
**{{color c="red" text="not recommended:"}}**
if (($fh = fopen($rssFile,'w')) === FALSE) {
die('Failed to open file for writing!');
**{{color c="green" text="recommended:"}}**
$fh = fopen("file.txt","r");
if (FALSE == $fh) {
die('Failed to open file for writing!');
==True before False in if/then/else==
To ensure readability, keep the True part of the check in the //if//-segment, and the False part in the //else//-segment. This will ensure that the code is easy to read and that the logic is not obscured regarding the execution path.
**{{color c="red" text="not recommended:"}}**
need example
**{{color c="green" text="recommended:"}}**
need example
==Do execute functions before conditionals ==
Executing functions inside conditionals can be quite difficult to read. This is double true for programmers new to PHP
if (FALSE === ($fh = fopen($rssFile,'w'))) {
...
**{{color c="green" text="recommended:"}}**
$fh = fopen("file.txt","r");
if (FALSE == $fh) {
...
==Constant must come before variable ==
Very often a logical bug is due to assignment inside the conditional. Assigning //the value 12 to the varible $inputNumber// will always yield true, but trying to assign //the variable $inputNumber to the number 12// will result in a error.
if ($inputNubmer == 12) {
...
**{{color c="green" text="recommended:"}}**
if (12 == $inputNumber) {
...

Revision [17383]

Edited on 2007-08-09 15:22:33 by JavaWoman [adding missing TOC item]
Additions:
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Variables_and_parameters">Variables and parameters</a></li>

Revision [17382]

Edited on 2007-08-09 15:18:50 by JavaWoman [some long-used rules added (about time)]
Additions:
A very widely-used rule that we'd like to see in Wikka (if only for consistency with most of the rest of the world!) is the following:
~-class and object names start with a **capital**
Unfortunately, the original authors of Wikka (or, more likely, Wakka) must have been unaware of any such rule so what we currently have mostly violates this. But that's not a reason to continue to do so... at least any new class, object, method or variable should follow this rule, and then at one time we can do a global search-and-replace and be done.
// examples to be added//
A very widely-used rule that we'd like to see in Wikka (if only for consistency with most of the rest of the world!) is the following:
~-method and function names start with a **lowercase character**
Unfortunately, as in the case of Class and object names (above), the original authors of Wikka (or, more likely, Wakka) must have been unaware of any such rule so what we currently have mostly violates this. But that's not a reason to continue to do so... at least any new class, object, method or variable should follow this rule, and then at one time we can do a global search-and-replace and be done.
In addition to this basic rule, we add:
~-method and function names should be descriptive, and use camelCaseWords to separate words
~-methods/functions returning a boolean (TRUE or FALSE) should have a name that naturally suggests this, such as isRegistered or existsPage
// examples to be added//
Constants should follow the same conventions as variables, except use all UPPERCASE to distinguish them from variables.
Similarly, when using associative arrays, avoid using double quotes. Unless using a variable as the key (in which case there should be no quotes at all!), include the key name within single quotes to prevent any ambiguities, especially with constants:
===Variables and parameters===
Be consistent in naming variables and parameters. Use the same name for the same type of thing, even in an unrelated bit of code: it makes reading and understanding code much easier. For instance:
~-if you're building a complete SQL query, use $sql or $query
~-if you're building (content for) a particular SQL //clause//, don't name that $sql, but name it after the clause it's intended for: $where, $values or $valuelist, $sort
~-to refer to an array that contains a complete page record, use $page; to refer to the name only, do **not** use $page, but instead $tag or $pagename
~-similarly, to refer to an array that contains a complete user record, use $user; to refer to the name only, use $username (or a variant like $reg_username or $anon_username that clearly indicates it's a //name//, not a whole record).
There are still quite a few cases where these rules are violated in our current code - they make the code much harder to understand, in particular when inappropriate or inconsistent names are used as formal inside methods and functions. Please correct when you come across such cases (after making sure you understand what's //really// meant) - and of course don't create any new ones. :)
Deletions:
Constants should follow the same conventions as variables, except use all uppercase to distinguish them from variables.
Similarly, when using associative arrays, avoid using double quotes. Include the key within single quotes to prevent any ambiguities, especially with constants:

Revision [17378]

Edited on 2007-08-08 14:10:58 by JavaWoman [minor]
Additions:
In spite of (or because of!) PHP's dynamic variable types, it is often necessary to make sure a variable is of a specific type before working with (or accepting) it. (It is also advisable to actually use a boolean whenever an either/or choice is needed, instead of a number, let alone a string representing a number!) Although for instance ##intval($var)## is equivalent to ##(int) $var## the latter is much more readable especially inside expressions that already have a numerous brackets. The same applies to ##array($var)## vs ##(array) $var##.
~-do not use any white space within the typecast operator, and do separate it with a single space before the variable or expression being cast
Deletions:
In spite of (or because of!) PHP's dynamic variable types, it is often necessary to make sure a variable is of a specific type before working (or or accepting) it. (It is also advisable to actually use a boolean whenever an either/or choice is needed, instead of a number, let alone a string representing a number!) Although for instance ##intval($var)## is equivalent to ##(int) $var## the latter is much more readable especially inside expressions that already have a numerous brackets. The same applies to ##array($var)## vs ##(array) $var##.
~-do not use any white space within the typecast operator, and do separate it it with a single space before the variable or expression being cast

Revision [17377]

Edited on 2007-08-08 14:08:59 by JavaWoman [adding type casting rules]
Additions:
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Type_casting">Type casting</a></li>
===Type casting===
In spite of (or because of!) PHP's dynamic variable types, it is often necessary to make sure a variable is of a specific type before working (or or accepting) it. (It is also advisable to actually use a boolean whenever an either/or choice is needed, instead of a number, let alone a string representing a number!) Although for instance ##intval($var)## is equivalent to ##(int) $var## the latter is much more readable especially inside expressions that already have a numerous brackets. The same applies to ##array($var)## vs ##(array) $var##.
~-use any of the following type casting forms:
~~-(int), (integer) - cast to integer; preferred form (int)
~~-(bool), (boolean) - cast to boolean; preferred form (bool)
~~-(float), (double), (real) - cast to float; prefered form (float)
~~-(string) - cast to string
~~-(array) - cast to array
~~-(object) - cast to object
~-do not use any white space within the typecast operator, and do separate it it with a single space before the variable or expression being cast
**{{color c="red" text="not recommended:"}}** (incorrect use of type casting decreases readability)
if (3 > intval($this->GetConfigValue('some_setting')))
$setting = (bool)$settingpar;
$param = array($param);
**{{color c="green" text="recommended:"}}** (correct use of type casting increases readability)
if (3 > (int) $this->GetConfigValue('some_setting'))
$setting = (bool) $settingpar;
$param = (array) $param;

Revision [16146]

Edited on 2007-02-16 16:53:13 by JavaWoman [comment about naming constants, and starting (one of) new subpages]
Additions:
~& While these general guidelines for naming constants are (mostly) fine, in working on the language file (to enable localization of Wikka) I found the ones presented are actually far too vague for specific usage. Constants have many uses, and different uses actually warrant their own guidelines. Naming constants to be used for regular expression building is quite a different proposition from naming constants for defining default values for parameters, or for text strings for a language file to be used by translators for localizing Wikka. So, I'm going to start a few subpages for developing guidelines for naming different **groups** of constants. I'm putting this comment here, on purpose, because what follows about names for text constants will (ultimately) be largely replaced by one or more specific subpages. So, for now, I think we'll need these (and possibly more) pages:
~~-CodingGuidelinesTextConstants - for (to be localized) text appearing in in the Wikka userinterface
~~-""CodingGuidelinesRegexConstants"" - for a collection of Regular Expressions and RE "building blocks"
~~-""CodingGuidelinesDefaultConstants"" - for defining default values for action, handler, or form default values
~&-- JavaWoman

Revision [15593]

Edited on 2006-11-03 18:57:33 by JonAmgine [appropriate jargon, general pedanticisms]
Additions:
~##include## and ##require## are **//statements//**, not functions. The parentheses (as in the little quote above) are optional in PHP. (According to the [[PHP:include include docs]]: "Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.") ---
~So, in order to make them not //look// like a function, it's best to leave out the parentheses, reserving their use exclusively for functions, never for statements. ---
~It is possible to ##include## or ##require## a file only conditionally. Obviously useful for blocks of content to be displayed, but it can also be more efficient to not require a library file unless it's really needed: for instance only after you've done input validation and concluded that it's OK to proceed. This can improve performance by not needlessly including code never executed. ---
Deletions:
~##include## and ##require## are **//statements//**, not functions. The brackets (as in the little quote above) are optional in PHP. (According to the [[PHP:include include docs]]: "Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.") ---
~So, in order to make them not //look// like a function, it's best to leave out the brackets (use those exclusively for functions, never for statements). ---
~It is possible to ##include## or ##require## a file only conditionally. Obviously useful for blocks of content to be displayed. But it can also be efficient not to require a library file unless it's really needed: for instance only after you've done input validation and concluded that it's OK to proceed: this will make the code more efficient by not needlessly including code that may not be executed. ---

Revision [15440]

Edited on 2006-10-07 12:18:31 by BrianKoontz [vim settings]
Additions:
~& Suggested settings for vim:
:set ai (Auto indent)
:set noet (Don't change tabs into spaces "on the fly")
:set ts=4 (4 spaces per tab)
~& Use the following global search/replace sequence to replace groups of four spaces with tabs (to get the ^I character, do a CTRL-V followed by a Tab):
:%s/ /^I/g

Revision [15231]

Edited on 2006-08-24 09:28:11 by MoKoshi [Fixed a typo: ony->only]
Additions:
Many editors can help implementing some of the coding standards and not only enforce consistency this way, but save you a bunch of time as well. A good "programmer's" editor will have settings to enforce line endings (when creating a new file and/or when saving a file) and for gettng rid of spurious white space at the end of lines (as a function, or as a settnig to automatically do this when saving a file).
Deletions:
Many editors can help implementing some of the coding standards and not ony enforce consistency this way, but save you a bunch of time as well. A good "programmer's" editor will have settings to enforce line endings (when creating a new file and/or when saving a file) and for gettng rid of spurious white space at the end of lines (as a function, or as a settnig to automatically do this when saving a file).

Revision [14759]

Edited on 2006-06-30 13:55:58 by DarTar [fixing toc]
Additions:
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Code_structure">Code structure</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_include_and_require"><tt>include</tt> and <tt>require</tt></a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Conditions_and_loops">Conditions and loops</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Naming_conventions">Naming conventions</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Class_and_object_names">Class and object names</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Method_and_function_names">Method and function names</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Variable_names">Variable names</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Constant_names">Constant names</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Loop_indices">Loop indices</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Code_layout">Code layout</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Braces">Braces</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Single_vs._double_quotes">Single vs. double quotes</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Whitespace">Whitespace</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Wikka-specific_guidelines">Wikka-specific guidelines</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Code_structure_1">Code structure</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Using_core_methods">Using core methods</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Actions_vs._handlers">Actions vs. handlers</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Action_parameters">Action parameters</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_File_naming_conventions">File naming conventions</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Third-party_code">Third-party code</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Editor_settings">Editor settings</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Tabs_vs._spaces">Tabs vs. spaces</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Trailing_whitespace_2">Trailing whitespace</a></li>
<li><a href="http://wikkawiki.org/CodingGuidelinesHowto#hn_Line_endings">Line endings</a></li>
Deletions:
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_structure">Code structure</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_include_and_require"><tt>include</tt> and <tt>require</tt></a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Conditions_and_loops">Conditions and loops</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Naming_conventions">Naming conventions</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Class_and_object_names">Class and object names</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Method_and_function_names">Method and function names</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Variable_names">Variable names</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Constant_names">Constant names</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Loop_indices">Loop indices</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_layout">Code layout</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Braces">Braces</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Single_vs._double_quotes">Single vs. double quotes</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Whitespace">Whitespace</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Wikka-specific_guidelines">Wikka-specific guidelines</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_structure_1">Code structure</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Using_core_methods">Using core methods</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Actions_vs._handlers">Actions vs. handlers</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Action_parameters">Action parameters</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_File_naming_conventions">File naming conventions</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Third-party_code">Third-party code</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Editor_settings">Editor settings</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Tabs_vs._spaces">Tabs vs. spaces</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Trailing_whitespace_2">Trailing whitespace</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Line_endings">Line endings</a></li>

Revision [14744]

Edited on 2006-06-30 11:55:58 by DarTar [moving phpdoc guide to separate page]
Additions:
>>==See also:==
~-[[DocumentingCodeHowto Code Documentation Tutorial]]
>>The following guidelines describe coding conventions adopted in Wikka. Please note this page is a //draft// - once it is completed, new and existing code should be made compliant with these guidelines.
Deletions:
{{lastedit}}
The following guidelines describe coding conventions adopted in Wikka. Please note this page is a //draft// - once it is completed, new and existing code should be made compliant with these guidelines.
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_documentation">Code documentation</a></li>
<ul>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_phpDoc_docblocks">phpDoc docblocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Special_markers">Special markers</a></li>
</ul>
====Code documentation====
Documentation is essential! Even well-written code is not necessarily self-documenting; there is always some decision-making involved, for instance, in **why** you coded something the way you did, why a particular algorithm is chosen, etc. Such "why" decisions should be documented. Also, pieces of code that need to be **used** by others, such as classes and functions (and in Wikka this includes actions and handlers) need to have their interface documented so others can make use of the functionality without needing to read all the code first.
In fact, when starting to write something new, it's a good idea to start with the documentation - and then work that out into code.
It's important that such documentation "travels with" the code, instead of having it externally. That's where comments come in, and specific guidelines for how to write comments for multiple purposes. A tool like [[http://www.phpdoc.org phpDocumentor]] can help to make a user-friendly and cross-referenced documentation for others to use by parsing the code looking for structures like classes and functions and for structured comments, and outputting fully-crossreferenced HTML documentation.
===phpDoc docblocks===
>>This section uses materials adapted from the phpDoc [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock manual]]>>Self-documenting code can be created by adding phpDoc **docblocks**. Every //file//, //class//, //function// and - where needed - //constant// or //variable// should be introduced by a docblock.
A docblock is an extended ##""C++""##-style PHP comment that begins with ##**""/**""**## and has an ##**""*""**## at the beginning of every line. Docblocks always //precede// the element they are documenting.
/**
* The most basic Wikka function.
*/
function foo()
A docblock contains three basic segments in this order:
~-Short Description
~-Long Description
~-Tags
The **Short Description** starts on the first line, and can be terminated with a blank line or a period. A period inside a word is ignored. If the Short Description becomes more than three lines long, only the first line is taken. The **Long Description** continues for as many lines as desired and may contain html markup for display formatting. Here is a sample docblock with a Short and a Long Description:
/**
* Display information about the system Wikka is running on.
*
* Depending on the 'show' parameter, this action displays different types of system information.
* By default it only displays this information to Wikka Admins, this option can be changed by
* setting 'public_sysinfo' to '1' in the Wikka configuration file.
*
* Syntax:
* {{system [show="OS|machine|host"]}}
*
*/
You can optionally use a [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc limited set of HTML elements]] in the Long Description if needed. Long Descriptions can also contain lists like in the following example:
/**
* Simple DocBlock with simple lists
* Here's a simple list:
* - item 1
* - item 2, this one
* is multi-line
* - item 3
* end of list. Next list is ordered
* 1 ordered item 1
* 2 ordered item 2
* end of list. This is also ordered:
* 1. ordered item 1
* 2. ordered item 2
*/
%%
The last (and most important) part of a docblock contains **tags** that add information on the documented item. Tags are single words prefixed by a ##**@**## symbol.
Wikka uses a subset of all the possible tags supported by phpDoc (for the complete list of phpDoc tags check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]])
/**
* A short description
*
* As many lines of extendend description as you want {@link element}
* links to an element {@link http://www.example.com Example} links to
* a website.
*
* @access public or private
* @author Author Name <author@email>
or
* @author {@link http://wikkawiki.org/UserPage author name} (further notes)
* @copyright name date
* @deprecated description
* @example /path/to/example (include an external example file with syntax highlighting)
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @ignore
* @internal private information for advanced developers only
* @link URL
* @name Name of the handler/action/formatter, e.g. recentchanges
* @package package name, e.g. Handlers
* @param type [$varname] description
* @return type description
* @see name of another element that can be documented (displays an internal link to the documentation for that element)
* @since Wikka version number
* @subpackage sub package name, e.g. Page (for page handlers)
* @todo item for a todo lisy
* @var type a data type for a class variable
* @version version (will use SVN $Id$)
*/
function foo()
// ...
(stub - file/class/function/constant/variable - refer to page with templates)
===Single-line comments vs. comment blocks===
===End-of-line comments===
===Special markers===
(stub - conventions for things like "todo" and "fixme" remarks)

Revision [14743]

The oldest known version of this page was created on 2006-06-30 11:49:42 by DarTar [moving phpdoc guide to separate page]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki