Mayon Coding Guidelines

This wiki provides guidelines for contributing code to the Agasti project, with the aim of creating a consistent, readable, and maintainable codebase. The goal of this document is to aid in understanding the internal workings of Agasti, as well as to make it easier to contribute code that blends well with the existing codebase.

Adhering to these guidelines will make it easier for others to understand your code and integrate your contributions.

Because Agasti is written using the Symfony framework, much of the formatting and naming guidelines are modelled on coding standards supplied by the Symfony Project: http://trac.symfony-project.org/wiki/HowToContributeToSymfony#CodingStandards

General

Do not use backticks for executing shell code.

  // Do not do this!
  // Note the backtick characters around the uptime command
  $uptime = `uptime`;
  // Do this...
  $uptime = exec('uptime');
  // ... or this
  exec('uptime', $uptime);

Use full-form tags to delimit PHP code. Do not include an end tag at the end of the file.

  <?php
  // Put some code here
  // No closing tag. This is the last line of the file.

Do not suppress error reporting. Leave this to the web server configuration.

Comments and Documentation

All classes should begin with a title block describing the basics of the class and the author at a minimum.

  /**
  * A description of the class goes here
  * 
  * @author is used to label the author
  */

All public functions should be labelled using Doxygen commands. A basic description should be included before the declaration:

  /**
  * A description of the function goes here
  * @return is the label used for returns
  * @param can describe any parameters
  */
  <the declaration of the function begins in this line>

Use Doxygen-compatible comments to document function purpose and usage. You can learn how to use Doxygen at the following URL: http://www.stack.nl/~dimitri/doxygen/docblocks.html

File Naming, Directory Structure, and Permissions

For any files that contain PHP code, the filename must end with “.php”. This prevents information disclosure by servers that are not configured to process files with other extensions like “.inc” as PHP. If you want to differentiate include files, end the filename with “.inc.php”.

Templates go under the “templates/” subdirectory, which should be restricted from direct access by clients in the web server configuration.

For files that define a class, name the file after the class name. As a standard, one file should contain one class.

Assume that your PHP files will be readable and executable, but not writable (chmod 755 in Unix).

Design Patterns

When passing a variable to a function by reference, define this in the function's definition.

  public function agModifyShelter(&$shelterObject)

Including a file should never result in code being executed. Code execution should only happen if a class is instantiated or a function is called.

Similarly, simply instantiating a class should never result in any data being written to the database or file system until a function in the class is called.

Global variable use is highly discouraged.

Global constant use is highly discouraged. Constants should be declared in classes and referred to through those classes.

If a function requires a parameter that is an object or an array, use type hinting in the function definition to make it easier for others to use the function.

When using variable expansion in double-quoted strings, avoid using complicated references.

  // Bad practice
  $string = "There are {$shelters->activeShelterCount} active shelters.";
  // Good practice
  $activeShelters = $shelters->activeShelterCount;
  $string = "There are $activeShelters active shelters.";

If a function has one or more optional parameters, these should come last in the list of parameters, ordered by frequency of use. A function should always work without the optional parameters being specified.

Naming and Capitalization

Start variable names with a lowercase letter, capitalizing every following word in the name. Do not use underscores. Use the same style for function names. Prefix Agasti classes with “ag” and use camel-case for the rest of the name.

Be verbose and descriptive about what functions do and what variables are used for. Terse variable names are acceptable for short loop iterators.

  var shelterPersonCount;
  function getShelterPersonCount()
  class agShelterTransport
  // This is acceptable if the code block is under ~20 lines long
  for ($i = 0; $i <= 10; $i++) {
  print($i); 
  }

When a camel-case name includes an acronym, capitalize only the first letter of that acronym.

  class agShelterHtmlViewer
  var shelterHtmlViewer;

Prefix protected variable names with an underscores.

  protected $_shelterInventory;

For constants – variables that will not change during execution – use all caps with underscores.

  define("FIRST_DAY_OF_WEEK", 0);

When you are creating variables that correspond to database column or table names, use the same name for the variable as the database object name, substituting camel-case for underscores. For example a field called shelter_name would become shelterName..

File Formats

Indent your code with 2 spaces and do not use tab characters. When saving files, use the Unix standard for terminating lines (newline character). Save files using the UTF-8 encoding. All of these settings are configurable in most text editors. Whitespace and Formatting

Work to limit your code blocks to 60 lines of code. If a code block grows larger, it should probably be refactored.

Code and comment lines should be no longer than 100 characters long. Only one statement should be written per line. Long database queries and other strings should also be split into multiple lines if they exceed 100 characters.

When creating a class or a function, open and close its code block braces on a separate line. When writing an if statement, for loop, or while loop code block, open the brace on the same line as the if statement and close it on its own line. Do not include extra spaces inside parentheses.

  if ($a == $b) {
  //some code here
  }

Include a space after a comma separating parameters, array members.

When concatenating strings, include spaces around the concatenation operator (period.)

Database Access

Always use the Symfony database layer to access the database. Use Doctrine ORM objects to access the database whenever possible. Do not access the database directly through built-in PHP functions.

Do not make any schema changes during runtime. Any schema changes to accommodate a module should be done at install time.

Try to avoid using temporary tables, using views whenever possible.

HTML

Use Symfony to generate output HTML whenever possible. Comments should be used sparingly in HTML as most code is self explanatory. All HTML code should validate through the w3c validator, available at: http://validator.w3.org/

When pure HTML is being outputted, adhere to W3C standards, available at: http://www.w3.org/TR/#tr_HTML

CSS

Use the same general whitespace rules for CSS – two-space tabs, spaces after semicolons.

If a class or ID has more than one attribute defined, split them into multiple lines, one per attribute.

  a {
  color: blue;
  font-size: larger;
  }

Use comments sparingly in CSS, in adherence with W3C standards available at:

http://www.w3.org/TR/#tr_CSS


QR Code
QR Code agasti:developer:coding_guidelines (generated for current page)