Coding rules

From Openflyers

Jump to: navigation, search

Contents

Introduction

We try, each time it's possible, to comply with PEAR coding standards.

Real coding rules (for all languages)

  • All functions should be pure: 2 calls to a function with same parameters should return the same result

see:

Page-setting

As say, just above, we try to comply with PEAR coding standards, and so on, PEAR formatting standards.

We use (names are from PHPEdit software):

  • 4 spaces indentation
  • space after start bracket
  • space before end bracket
  • space after if
  • space after switch
  • space after while
  • space before start angle bracket
  • space after end angle bracket
  • extra padding for case statement
  • one true brace function declaration
  • glue amperscore
  • glue arrow
  • change shell comment to double slashes comment
  • force large php code tag
  • force true false null contant lowercase
  • align equal statements
  • optimize eol
  • rewrite only documentation comment

We do NOT use:

  • indent with tab (indent with space instead)
  • align equal statements to fixed pos
  • remove comments
  • one true brace

Release number rules

  • A published release is a release that is zipped and accessible by public via openflyers.org.
  • We use X.Y.Z release number format to name published releases.
  • In X.Y.Z release number format, the Z should be 0 except for minor bug patches.
  • When a new release is ready, we tag it via CVS (ie: 1.2.0).
  • The first changed after a tagged release should be name by a new release number in the config.php (OF_RELEASE const). The number format should be X.Y.Zalpha
  • When the release is mature enough to be tested, it should be renamed X.Y.Zbeta and tagged in CVS.
  • If several beta release should be tagged, the number format should X.Y.Zbeta1, X.Y.Zbeta2, etc.
  • When a release is ready to be tested in production, it should be renamed X.Y.Zrc1 and tagged via CVS.

General rules

  • Write false and true in small. Doing this, we are compatible with JavaScript format.
  • We use an indent of 4 spaces, with no tabs (see : PEAR standard indenting).
  • We use standard unix end of line : \n.
  • Functions are named like that : fooFunction (see : PEAR function definitions)

Naming conventions

We follow PEAR Naming Conventions and in addition:

  • Class name begin with an upper case (like PEAR) but words are not separated by underscore.

Example: 

ThisIsAClassName
  • All variables and functions are written like PEAR rules even for javascript variables and POST/GET variables.

Example: 

PHP       : $thisIsAnExample
JavaScript: thisIsAnExample
POST/GET  : thisIsAnExample

SVN rules

After and before sending a commit to the SVN, preliminary tests must be done in order to check that core functionalities of OpenFlyers work without any problems. These functionalities are :

  • Authentication
  • Booking
  • Flight


Each time someone do an update from the SVN to server(s), he has to alert the coding team. So it will be faster to correct incoming bugs by checking logs.


In order to avoid massive useless bugs for live server, below a rule to apply :

  • Each new development will be done into a new SVN branch then alert coding team. Only are concerned long term developments which could have impact onto core functionalities
  • Reported bugs will be corrected to the SVN trunk, then the trunk will be merge to the branch in order to apply the bug patch to the branch
  • Merge branch into the trunk when the current development is finished and stable then alert coding team

Documentation about this : http://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-dug-merge.html

Directory and files rules

Introduction

Adopted philosophy is as follows  :

  • Directory structure of is mainly flat in order to facilitate research.
  • Non php files must be gathered by type in directories whose name corresponds to the type of file. That amongst other things makes it possible to know which are the rights of access which it is necessary to give to these directorues (and files) on a host.
  • php files that are accessible from a client browser via http should be in the root directory.
  • file names should be of the following form : thisIsCorrect.php except for class files ( ThisIsCorrect.php )

répertoire admin

Contient tous les fichiers de la partie admin d'OF.

répertoire accounts

Fichiers relatifs à la gestion des comptes pilotes côté admin.

répertoire flights

Fichiers relatifs à la gestion des vols côté admin.

répertoire cache

Contient les caches des fichiers xml décrivant les menus (cahier ou admin).

classes directory

Contains all project classes. Thus, they are classes which belong to main part of the OpenFlyers system. Rules :

  • each file shall contain only one class.
  • filename is the class name.

Do not forget that according to the rules, class name is written DummyClassName

Date subdirectory

displayClasses subdirectory

Contains all the classes of the project which make display (HTML only for the moment).

Mail subdirectory

mailing_list subdirectory

srss subdirectory

répertoire conf

Ce répertoire contient deux fichiers :

  • config.php contient toutes les constantes liées à la configuration d'OF. Les éléments configurables à ce niveau sont donc laissés au bon soin de l'hébergeur contrairement aux éléments de la table parameter de la base de données qui sont accessibles par le gestionnaire de club.
  • connect.php contient les éléments pour accéder à la base de données

Un "deny from all" est évidemment le bienvenu dans ce répertoire

répertoire css

Contient toutes les feuilles de style.

répertoire documentations

Répertoire qui contient des fichiers à destination des développeurs

répertoire img

Contient toutes les images (extension png, gif). img directory should contain only true image files.

répertoire includes

Répertoire amené à disparaitre. Contient des éléments permettant de fabriquer la partie cahier et interface résa.

répertoire accounts

Contient les fichiers relatifs à la gestion des comptes pilotes côté cahier.

répertoire flights

Contient les fichiers relatifs à la gestion des vols côté cahier.

répertoire install

Contient les fichiers necessaires à une nouvelle installation ou à une mise à jour.

répertoire sql

Contient tous les fichiers sql. Pratiquement il y a un seul fichier qui est nécessaire à l'install (nouvelle installation uniquement)

répertoire javascript

  • Contient tous les fichiers javascripts.
  • Normalement, les noms des fichiers javascript correspondent pour l'essentiel au nom du fichier php qui l'appelle.
  • javascript directory should contain only static javascript files (with extension .js).

répertoire accounts

Contient les fichiers javascript relatifs à la gestion des comptes pilotes (cahier et admin).

répertoire flights

Contient les fichiers javascript relatifs à la gestion des vols (cahier et admin).

répertoire lang

Amené à disparaître. Contient toutes les langues.

répertoire pool

Contient les fichiers contenant des fonctions plus ou moins génériques et utilisées un peu partout dans le code.

répertoire xml

Contient tous les fichiers xml

répertoire xsl

Contient toutes les feuilles de style xslt

PHP rules

  • Use <?php tab instead of <? . We recommand to set short_open_tag Off in the php.ini file.
  • Configure PHP to display "notice" report.
  • Use simple brackets (ex : echo('houhou');) instead of double brackets (ex : echo("houhou");).
  • according to PEAR rules, private variables should begin with an underscore (ie: _name).
  • XHTML open-tags should have his miror closing-tag in the same php file.
  • In a function declaration, the order of "static", "public" and "function" should be this: 
static public function someFunction()

So you are sure to find the function declaration by searching "function someFunction"

SQL rules

Table engine

  • engine should be MyISAM

Table names

  • Table names should be singular (ie: member is correct, members is not).
  • Table names should be written with lowercase (ie: member is correct, MEMBER is not).

Field names

  • Field names should be written with lowercase(ie: id is correct, ID is not).
  • Field names should NOT correspond to SQL commands name.
  • Field names should be defined with NULL authorized except for primary key.
  • Primary key of the table should be named id.
  • Foreign key should be named sometable_id.
  • keys should be INT(10) UNSIGNED.

REQUETES

  • When using INSERT instruction, the field names should be always mentionned allowing thus table changes without rewriting needs. Ex: 
INSERT INTO toto '''(id,name)''' VALUES ('1','test')
  • In a SELECT request, it's forbidden to mix up several tables sources and joins. Ie: 
SELECT table1.name1, table2.name2 FROM table1, table2 LEFT JOIN name3 ON table3.name3=table1.name4 WHERE table2.name2=table1.name5

is bad and should be replaced by 

SELECT table1.name1 FROM table1 LEFT JOIN name3 ON table3.name3=table1.name4 LEFT JOIN table2.name2 ON table2.name2=table1.name5
  • When using a LEFT JOIN instruction, the left part of the ON clause should always refer to a field of the joining table

Example: 

SELECT * FROM table1 LEFT JOIN table2 ON table2.table1_id=table1.id

and not this: 

SELECT * FROM table1 LEFT JOIN table2 ON table1.id=table2.table1_id
  • using LIMIT first_row,nb_of_rows in SELECT requests is not SQL standard compliant. The correct syntax is LIMIT nb_of_rows OFFSET first_row.

As we are using PEAR::MDB2, we should even use the MDB2 syntax (because MDB2 emulates the LIMIT clause if the database doesn't support it) : 

$db->setLimit(30, 0);
$result = $db->query('SELECT * FROM users');
  • please use SQL standard types and not mysql ones ! (for instance, do not use tinyint or int(8) syntax)
  • When a boolean is needed, use the 'boolean' type and TRUE or FALSE in the queries (instead of int and 0/1)
  • do not use " character to enclose strings in queries, but '. Even better, you should consider using MDB2 prepare/execute functions 
$stmt = $mdb2->prepare('INSERT INTO translation(french, english) VALUES(?,?)', array('text', 'text'), false);
$res = $stmt->execute( array('moi', 'me') );
  • instead of using columns of type "date not null default 0000-00-00", use "date" it's better for compatibily reasons & it's more beautiful ;)
  • use boolean expressions in WHERE clauses. "WHERE field & binary_mask" is bad because "field & binary_mask" is an integer. use "WHERE (field & binary_mask) > 0" instead
  • there is no "unsigned" integer defined in SQL standard types (even if these types are available in mysql).

XHTML rules

  • XHTML should be XHTML 1.0 strict with the following header : 
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 
  • Empty attributs, in XHTML, should be written by setting them equals to themselves (ex : selected="selected")

DHTML rules

Using DHTML capabilites should be restricted such that browsers incompabilities should not block the use of OF.

class rules

  • Every class should be save in an appropriate directory :
    • classes directory, for all classes do not displaying anything
    • displayClasses directory, for all classes dealing with displaying something
  • Public methods should only need in/out object parameters and not id parameter.

Database description rules

  • Database description named Database_description.html should be created with the data dictionary from phpMyAdmin.
  • The comment field should include within brackets and in capital letters the key type when existing and attached.
Retrieved from "http://wiki.openflyers.org/index.php/Coding_rules"
Personal tools