1.5 Template Project

The Joomla! Documentation Working Group is running a project to develop detailed reference and tutorial material on Joomla! 1.5 templates.  There is a project page on the documentation wiki where you can see the work in progress and help us by contributing your knowledge.

Who's Online

We have 7 guests online

Help Site License

The Joomla! Help Site content is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution NonCommercial ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Home arrow Developer Manual arrow Appendix arrow D. Code and Commenting Standards

D. Code and Commenting Standards PDF Print E-mail
A small subset of the available commenting tags are shown in the following examples. For more details, see the phpDocumentor documentation.
File Header Comment

All php files must have the following comment block after the opening php tag:
/**
* This is a broad desciption of the file function
* @version $ Id $
* @package Joomla
* @copyright Copyright (C) 2005 Open Source Matters. All rights reserved.
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL, see LICENSE.php
* Joomla! is free software and parts of it may contain or be derived from the
* GNU General Public License or other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/
This example is used for core files. Replace the description with a brief statement of what the file is for. Where files are stored in a CVS, the $ Id $ tag (remove the spaces around the Id text) otherwise use whatever version numbering system you care to employ. Replace the copyright and license with the appropriate details.

The package should be a single word (no spaces) that describes the application this file is a part of. For example, all core files are in the Joomla package. A third party element called Super Forum may be given the package name of SuperForum. When the documentation is compiled by phpDocumentor, it is grouped into it's respective packages.

Documenting Classes

Classes should be commented in the following way:
/** 
* A utility class
*/
 class mosUtility extends mosAbstractUtility {
  /** @var string A temporary string */
  var $temp;
 
  /**
  * Constructor
  * @param string A string to store
  * @return boolean True if the string is not empty, false otherwise
  */
  function mosUtility( $temp ) {
   $this->temp = $temp;
   return strlen( $temp ) > 0;
  }
 }
There are a number of comment blocks used here.

The first is placed before the class definition and should briefly describe what the class is. If the class has a tutorial document related to it, you can link this via the @tutorial tag.

For each class variable (for example, $temp) provide a comment block on the line before with the @var tag. The syntax is:
@var data-type description
For each class method provide a comment block. The first line should be a brief description. For each argument in the function statement, provide a @param tag and, if the function returns a value, provide a @return tag. Both tags have the same syntax as for the @var tag.

Abstract classes should include the @abstract tag as follows:
/** 
* An abstract utility class 
* @tutorial utility.cls 
* @abstract 
*/
 
 class mosAbstractUtility {
  // this class does nothing
 }

Documenting Functions

Functions are documented in the same way as class methods, for example:

/** 
* Strips html tags from a string 
* @param string The source string 
* @return string 
*/
 
 function mosStripTags( $text ) {
  return strip_tags( $text );
 }

Miscellaneous Documentation

Additional comment throughout the code should be used "just enough" to help you remember what you where doing when you haven't looked at the code for three weeks. To many comments just bulk the code and too few can reduce the effectiveness of a development team or even your own debugging.

You should include short notes before query statements describing what they are for (it's not always obvious just looking at the SQL). You should also use comments to breakup lengthy functions or class methods into logical clumps of code (for example, query data, validate, prepare output, etc).

Always use C-style comments, not Perl style (hash). Here are some examples:
// print something out, this is acceptable for a short note
echo $var;
 
/*
Here is something that needs a little more explanation
over a few lines.  This is acceptable.
*/
echo $var->complex();
 
## Avoid this style of comment
echo badPractice();
 
// ---------------------------------------------------------------------------------
// Try to avoid the ascii equivalent of a page break unless it is really necessary
// The bytes add up over time 

File Formats

Files must be committed to the CVS in Unix format.

Code Styles

The Joomla core scripts use a modifed Pear standard.  All indents must be made up of tab characters.

Language control blocks, such as if, while, switch, etc, have a space before the opening bracket but no space around the arguments in the brackets. There is a space between the last bracket and the opening curly brace (this is not on a new line). Subsequent lines are indented with a tab (generally set to the equivalent of 4 spaces in your editor for looks). The closing brace is outdented to align with the opening statement. For example:
if ($less < $more) {
    echo 'Here';
}
Functions have no space between the name and the opening bracket but have space around the enclosed arguments. This distinguishes them from language constructs. Arguments are separated by a comma-space pair. For example:
echo myFunction( $arg1, $arg2 );
 
if (myCompare( $arg1, $arg2 )) {
    echo 'My compare is true';
}
Switch statements should have indented "case" statements followed by indented code including the "break" statement. For example:
switch ($task) {
 
    case 'edit':
        doEditFunction( $option );
        break;
 
    case 'view':
    default:
        doViewFunction( $option );
        break;
}
Classes should naturally indent their methods. For example:
class foo {
 
  function bar( $hah ) {
    return "humbug";
  }
}

Anchor tags may be broken over two lines provided that the closing tag has not space between it and the contents of the tag, for example:

<a href="index.php">
    This is a really long link</a>

Table should be naturally indented, for example:

<table>
    <tr>
        <td>
            A cell
        </td>
   </tr>
</table>



Last Updated ( Thursday, 15 September 2005 )
 
< Prev   Next >