Web Development

Revision as of 07:30, 4 February 2009

Here we'll attempt to explain the process we'll be using to develop the next generation of the DareNET web site. We will rely heavily on community interaction, whether through the forums or on IRC (#dev). IRC is perhaps the best place to find members of the development team and discuss ideas, latest code and make general comments.

We'll maintain 3 versions of the site.

stable - for production (the version used on the main site) where stability is more important than features.
trunk - development version where features are important and stability is necessary.
branches - for testing, and development members interested in the most advanced feature set and willing to refine them some.

Coding Standards

Adding New Features

No new features should be added to trunk, without having their own tests - which should be passed before committing them to the repository. Any additions to stable should undergo a team vote.

Indentation

One tab will be used for indentation.

So, indentation should look like this:

<source lang="php" line start=1 > <?php // base level

   // level 1
       // level 2
   // level 1

// base level ?> </source>

Or:

<source lang="php" line start=1 > $booleanVariable = true; $stringVariable = "moose"; if ($booleanVariable) {

 echo "Boolean value is true";
 if ($stringVariable == "moose")
 {
   echo "We have encountered a moose";
 }

}</source>

Function Calls

Functions should be called without space between function's name and starting bracket. There should be one space between every parameter of a function call.

As you can see above there should be one space on both sides of equals sign (=). To increase the readability of the code you can add spaces (or tabs) before the equals sign, but only in the case of a multiple function call presented below:

Commenting Code

All comments should be written in English, and should in a clear way describe the commented block of code.

Comments can include the following phpDocumentor tags:

PhpDoc tags are very much like JavaDoc tags in Java. Tags are only processed if they are the first thing in a DocBlock line, for example: <source lang="php" line start=1 > <?php /**

* Tag example.
* @author this tag is parsed, but this @version is ignored
* @version 1.0 this tag is also parsed

/

?></source>

There are 3 inline tags ({@internal}}, {@inheritdoc}} and {@link}}). <source lang="php" line start=1 > <?php /**

* Example of inline phpDoc tags.
*
* This function works hard with {@link foo()} to rule the world.
*/

function bar() { } function foo() { } ?></source>

Including Files

When including files with classes or libraries, use only and always the require_once function.

PHP Tags

Always use long tags (<?php ?>) Instead of short tags (<? ?>).

Functions

Write all functions in camel case. <source lang="php" line start=1 > <?php function longFunctionName() { } ?></source>

Classes

Class names should be written in CamelCase, for example: <source lang="php" line start=1 > <?php class ExampleClass { } ?></source>

Variables

Variable names should be as descriptive as possible, but also as short as possible. Normal variables should start with a lowercase letter, and should be written in camelBack in case of multiple words. Variables containing objects should start with a capital letter, and in some way associate to the class the variable is an object of. Example: <source lang="php" line start=1 > <?php $user = 'John'; $users = array('John', 'Hans', 'Arne'); $Dispatcher = new Dispatcher(); ?></source>

Compatibility

Support for PHP 4 was discontinued over a year ago. We will assume the latest stable release of PHP 5 is running, and as such, will write code with that in mind.

Example Addresses

For all example URL and mail addresses use "example.com", "example.org" and "example.net", for example:

Email: someone@example.com
WWW: http://www.example.com
FTP: ftp://ftp.example.com

File Names

File names should be created with lower case. If a file name consist of multiple words, they should be divided by an underscore character, for example:

long_file_name.php

Variable Types

Variable types for use in DocBlocks:

mixed	A variable with undefined (or multiple) type.
integer	Integer type variable (whole number).
float	Float type (point number).
boolean	Logical type (true or false).
string	String type (any value in "" or ' ').
array	Array type.
object	Object type.
resource	Resource type (returned by for example mysql_connect()).

Remember that when you specify the type as mixed, you should indicate whether it is unknown, or what the possible types are.

Constants

Constants should be defined in capital letters: <source lang="php" line start=1 > <?php define('CONSTANT', 1); ?></source>

If a constant name consists of multiple words, they should be separated by an underscore character, for example: <source lang="php" line start=1 > <?php define('LONG_NAMED_CONSTANT', 2); ?></source>

Method Definition

Example of a function definition: <source lang="php" line start=1 > <?php function someFunction($arg1, $arg2 = ) {

 if (expr) {
   statement;
 }
 return $var;

} ?></source>

Parameters with a default value, should be placed last in function definition. Try to make your functions return something, at least true or false - so it can be determined whether the function call was successful. <source lang="php" line start=1 > <?php function connection(&$dns, $persistent = false) {

 if (is_array($dns)) {
   $dnsInfo = &$dns;
 }
 else
 {
   $dnsInfo = BD::parseDNS($dns);
 }
 if (!($dnsInfo) || !($dnsInfo['phpType'])) {
   return $this->addError();
 }
 return true;

} ?></source>

NOTE: There are spaces between the equals (=) sign.

Release Checklist

The following is a list of requirements that need to be satisfied when creating a release:

Create a change log with clean, readable descriptions, referencing tickets wherever possible.
Changes must be reflected in all written material prior to release.
The code must be tested.
The code should always be made available in the following archive formats: .tar.gz

* When referring to code availability, we specifically mean accessibility for team members, not the public. The code source should not be distributed outside of the team. Additionally, the change log should be posted on the development site wiki for easy viewing.

Version Scheme

We will be utilizing the following version scheme for the site:

Major revision:	#.0.0.0	Major code changes
Moderate revision:	0.#.0.0	Minor code changes
Minor revision:	0.0.#.0	Bug fixes - no major code changes
Build:	0.0.0.#	Refers to the SVN revision number at the time of the build.

@@ Line 117: / Line 117: @@
 <source lang="php" line start=1 >
 <?php
-function longFunctionName() {
+function longFunctionName()
+{
 }
 ?></source>