Log in | Back to darenet.org
Share

Web Development

m (→MVC)
Line 1: Line 1:
{{Header|1 = <h2>'''[[Development Team|DareNET Development Wiki]]''' - {{FULLPAGENAME}}</h2>}}
{{Header|1 = <h2>'''[[Development Team|DareNET Development Wiki]]''' - {{FULLPAGENAME}}</h2>}}
-
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.
+
This document outlines technical and style guidelines which are followed in website-darenet. Contributors should also follow these guidelines.
-
== MVC ==
+
==Spaces, Linebreaks and Identation==
 +
* Use one tab for each level of indentation.
 +
* Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
 +
* Use K&R style braces and spacing.
 +
* Put a space after control keywords like if and for.
 +
* Put a space after commas in argument lists.
 +
* Put a space around operators like =, <, etc.
 +
* Don't put spaces after function names.
 +
* Parentheses should hug their contents.
 +
* Generally, prefer to wrap code at 80 columns.
-
The goal is for website-darenet to follow the [[Wikipedia:Model-view-controller|Model-View-Controller]] (MVC) software design pattern. We'll take a brief look at what that means here.
+
==Case and Capitalization==
 +
* Name variables and functions using lowercase_with_underscores.
 +
* Name classes using UpperCamelCase.
 +
* Name methods and properties using lowerCamelCase.
 +
* Use uppercase for common acronyms like ID and HTML.
 +
* Name constants using UPPERCASE.
 +
* Write true, false and null in lowercase.
-
Programming using MVC separates your application into three (3) main parts:
+
==Comments==
 +
* Do not use "#" (shell-style) comments.
 +
* Prefer "//" comments inside function and method bodies.
-
# The Model represents the application data.
+
==PHP Language Style==
-
# The View renders a presentation of model data.
+
* Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
-
# The Controller handles and routes requests made by the client.
+
* Prefer casts like (string) to casting functions like strval().
 +
* Prefer type checks like $v === null to type functions like is_null().
 +
* Avoid all crazy alternate forms of language constructs like "endwhile" and "<>" (acceptable in templates).
 +
* Always put braces around conditional and loop blocks.
-
[[Image:Basic mvc.png]]<br>''A basic MVC request.''
+
==PHP Language Features==
-
 
+
* Use PHP as a programming language, not a templating language.
-
The figure above shows an example of a bare-bones MVC request. To illustrate, assume a client named 'Joe' just clicked on the 'Register a channel' link on the application's home page. Spelled out, here's what may have happened:
+
* Avoid globals.
-
 
+
* Avoid extract().
-
* Joe clicks the link pointing to <nowiki>http://www.darenet.org/register/channel</nowiki>, and his browser makes a request to the web server.
+
* Avoid eval().
-
* The dispatcher checks the request URL (/register/channel), and hands the request to the correct controller.
+
* Avoid variable variables.
-
* The controller performs application specific logic. For example, it may check to see if Joe has logged in.
+
* Prefer classes over functions.
-
* The controller also uses models to gain access to the application's data. Models usually represent database tables, but they could also represent LDAP entries, RSS feeds or files on the system. In this example, the controller uses a model to fetch a list of channels already registered to Joe from the database, and if Joe is currently op'd in the channel he wants to register.
+
* Prefer class constants over defines.
-
* Once the controller has worked its magic on the data, it hands it to view. The view takes this data and gets it ready for presentation to the client. Views in website-darenet will mostly likely be in HTML format, but a view could just as easily be a PDF, XML document or JSON object depending on needs.
+
* Avoid naked class properties; instead, define accessors.
-
* Once the view has used the data from the controller to build a fully rendered view, the content of that view is returned to Joe's browser.
+
* Use exceptions for error conditions.
-
 
+
-
Almost every request to a website-darenet application will follow this basic pattern. We'll add some details later on which are specific to website-darenet, so keep this in mind as we proceed.
+
-
 
+
-
=== Why MVC? ===
+
-
 
+
-
Because it is a tried and true software design pattern that turns an application into a maintainable, modular, rapidly developed package. Crafting application tasks into separate models, views and controllers will make website-darenet light on its feet. New features can then be easily added, and new faces on old features will be a snap. The modular and separate design will also allow for developers and designers to work simultaneously, including the ability to rapidly prototype. Separation will also allow developers to make changes in one part of website-darenet without affecting others.
+
-
 
+
-
== 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.
+
-
 
+
-
=== Braces ===
+
-
Braces should always be placed on lines of their own and match up vertically with their partner.
+
-
 
+
-
For example:
+
-
<source lang="php" line start=1 >
+
-
if (is_array($dns))
+
-
{
+
-
  $dnsInfo = &$dns;
+
-
}
+
-
</source>
+
-
 
+
-
=== 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.
+
-
 
+
-
<source lang="php" line start=1 ><?php
+
-
$var = foo($bar, $bar2, $bar3);
+
-
?></source>
+
-
 
+
-
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:
+
-
 
+
-
<source lang="php" line start=1 ><?php
+
-
$varShort = foo($bar1);
+
-
$variableLong = foo($bar1);
+
-
?></source>
+
-
 
+
-
=== 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:
+
-
 
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.access.pkg.html @access]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.author.pkg.html @author]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.copyright.pkg.html @copyright]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.deprecated.pkg.html @deprecated]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.example.pkg.html @example]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.ignore.pkg.html @ignore]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.internal.pkg.html @internal]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.link.pkg.html @link]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.see.pkg.html @see]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.since.pkg.html @since]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.tutorial.pkg.html @tutorial]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.version.pkg.html @version]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.inlineinternal.pkg.html inline {@internal}}]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html inline {@inheritdoc}}]
+
-
* [http://manual.phpdoc.org/HTMLframesConverter/phpdoc.de/phpDocumentor/tutorial_tags.inlinelink.pkg.html inline {@link}}]
+
-
 
+
-
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 [http://php.net/require_once 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:
+
-
 
+
-
<code>long_file_name.php</code>
+
-
 
+
-
=== Variable Types ===
+
-
 
+
-
Variable types for use in DocBlocks:
+
-
 
+
-
{| class="wikitable" width="60%" style="font-size: 85%; text-align: left;"
+
-
|-
+
-
| 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
+
-
 
+
-
<nowiki>*</nowiki> ''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.''
+

Revision as of 07:54, 16 June 2011

In This Guide:

DareNET Development Wiki - Web Development

This document outlines technical and style guidelines which are followed in website-darenet. Contributors should also follow these guidelines.

Spaces, Linebreaks and Identation

  • Use one tab for each level of indentation.
  • Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
  • Use K&R style braces and spacing.
  • Put a space after control keywords like if and for.
  • Put a space after commas in argument lists.
  • Put a space around operators like =, <, etc.
  • Don't put spaces after function names.
  • Parentheses should hug their contents.
  • Generally, prefer to wrap code at 80 columns.

Case and Capitalization

  • Name variables and functions using lowercase_with_underscores.
  • Name classes using UpperCamelCase.
  • Name methods and properties using lowerCamelCase.
  • Use uppercase for common acronyms like ID and HTML.
  • Name constants using UPPERCASE.
  • Write true, false and null in lowercase.

Comments

  • Do not use "#" (shell-style) comments.
  • Prefer "//" comments inside function and method bodies.

PHP Language Style

  • Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
  • Prefer casts like (string) to casting functions like strval().
  • Prefer type checks like $v === null to type functions like is_null().
  • Avoid all crazy alternate forms of language constructs like "endwhile" and "<>" (acceptable in templates).
  • Always put braces around conditional and loop blocks.

PHP Language Features

  • Use PHP as a programming language, not a templating language.
  • Avoid globals.
  • Avoid extract().
  • Avoid eval().
  • Avoid variable variables.
  • Prefer classes over functions.
  • Prefer class constants over defines.
  • Avoid naked class properties; instead, define accessors.
  • Use exceptions for error conditions.
Retrieved from "http://wiki.darenet.org/Web_Development"