SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Download

Contributing to SPIP development

A few rules valid for versions up until SPIP 1.7.2

June 2002 — updated on : August 2010

All the versions of this article:

If you’d like to contribute towards the programming of SPIP, the most important thing to keep in mind is the following: you are entering into a project which is already working well. The project is guided by a collection of rules which, as arbitrary as they may seem to the newcomer, ensure its continued consistency. Such rules do not necessarily need to be explicitly detailed in order for them to be currently active: some of them are clearly visible after even a cursory glance at the code, and the tacit rules ought to be respected just as much as the explicit ones.

Although this article suggests these rules apply up until version 1.7.2, they still largely apply today even to the latest version. Please be respectful of others, and we’ll all get along together much better.


It is formally recommended to follow these rules closely. This respect is not to be conditional upon your own personal tastes: it makes it possible to maintain a consistency and unity to the project, and to maintain legibility within the project to at least the level that it currently enjoys. Don’t forget that there are other people that you must consider who will need to read, understand and modify your code contributions.

For example, it’s clear that all SPIP functions are written in the form my_function(). Within this project, it will then be obviously out of place to add new functions defined in a format like MyFunction() - even if objectively speaking there is no substantial qualitative difference between the two.

Of course, this doesn’t totally exclude valid criticism of a given rule, nor the systematic exclusion of any proposition to improve on it. Please do not hesitate to make such propositions; but do make sure you have genuine, credible reasons to do so.

Finally, every rule has its exceptions. But such exceptions must have a genuine justification, not simply laziness on the part of the programmer; and they clearly need to be as rare as is possible. In particular, remember the common tendency to allow a "temporary" or "intermediary" solution to, by default, become the permanent solution when no one has the drive, desire or available time to correct it; it is a logical and fair expectation for any programmer to be fully responsible for their own code, and not that of any others who might temporarily stop by.

Presentation and coding rules

The rules that follow are common to a fairly extensive number of programming languages: at least to a fair number of languages that employ a syntax similar to that of PHP (i.e., C, C++, Java, etc.).

Such rules are commonly accepted "best practices", in as natural a manner as the rules for presentation and typography are established for any natural language; in addition, they are frequently quite similar.

Presentation

-  The code must be spaced and indented in a way that clearly reveals its structure and the various logical blocks (especially functions). Spacing and indenting must be sufficient to make the structure understandable right from the first glance; they must not be excessive either. The same type of care needs to be taken as with separating paragraphs of text in a natural language.

-  Indenting should be preferentially made by using the tab character. This leaves the choice of how many spaces that an indent actually represents open to by configured in the options specified for the programmer’s choice of text editor, and does not impose any such choice on any other developers.

-  Any block contained within a pair of braces { and } should be indented with one and only one tab. The same applies recursively for any sub-blocks: add one and only one additional tab for each increasing level of additional logical depth. This rule applies equally to the declaration of functions.

-  Code which is not part of a function should not be indented.

-  Any usage of PHP-HTML transitions (<?php and ?>) should be minimised. Particularly avoid them when only displaying little excerpts of HTML. Do not forget that a tiny segment of PHP code inserted into the middle of an ocean of HTML is by and large invisible without a very careful reading.

Typography

-  When using parentheses ( and ) or brackets [ and ], you should not leave any spaces immediately after the opening parenthesis or bracket, nor any spaces immediately prior to the closing parenthesis or bracket.

-  When using binary operators (+, =, *, AND, ...), you should leave a space on both sides of the operator. The obvious exception is illustrated in the previous sentence, where the operators are just referred to and not actually used as operators that they are.

-  Unary operators (!, ...) must be immediately adjacent to the parameter to which they apply.

-  By convention, when calling a function, there are no spaces immediately prior to the opening parenthesis: "f($x)" and not "f  ($x)". On the contrary, and to clearly demarcate the difference, we leave a space in front of the parenthesis when it entails a control structure that is integral to the language: "if  (!$x)" and not "if(!$x)". [1]

-  Commas and semi-colons are followed but not preceded by a single space.

Programming rules

Think

Before programming any new functionality, think first about...

-  the methods and algorithms used for its implementation: lightness, performance, stability (don’t overlook making some rough calculations to validate your choices);
-  suitability to the project: portability, security, flexibility;
-  implications on other functionalities: modifications and additions that will need to be made to other existing functionalities;
-  the "natural" place for this functionality within the entire project: in terms of interface, file locations, etc.

Do not overlook any refactoring or realigning of code that will be required (by functions, especially considering files that must be included). On the other hand, avoid wherever possible the inclusion of files containing non-function code (except where such inclusions are "natural" and deliberately intended).

Naming

-  Variables and functions:

For any project whatsoever, a standardised naming convention is essential for the resulting code to be legible. As such, within SPIP, the names of variables and functions are written in lower case: composed names are constructed with underscores, e.g. composed_variable_name.

Generally speaking, names should be neither too short nor too long: just sufficiently explanatory. This rule is particularly important for global variables which can be shared between several files and/or several functions. For local variables (i.e. used in only one function), the rule is more flexible. In particular, it is permitted to use variables of only a single letter in order to make complex expressions more compact. Note that in almost all programming languages, there are a certain number of particular letters which are traditionally employed for "standardised" usage (examples: $i, $j for loop counters, $n for numbering, $t for time or duration in seconds, etc.). Not contravening such standard industry practice will allow any future readers to more quickly understand what’s going on.

-  Files:

For historical reasons, files to be included in the public space following a naming convention of inc-filename.php. In the private space, however, this is normally written as ecrire/inc_file.php (using an underscore instead of the hyphen in the other case). Files in the public space called by HTTP redirection from the private space are named as spip_file.php. All other files must have names which DO NOT start with either "inc" or with "spip"- those are to be reserved only for the purposes mentioned above.

Language

PHP code is "naturally" written in something closer to English than any other language. Given as the SPIP project is originally and most frequently deployed and developed by francophones, it is considered polite behaviour to comment your code in French. If you are uncomfortable with this, or if your French is not perfect, still please do try to make the effort. Others will be genuinely grateful and more than happy to correct any errors of grammar or meaning that might slip through. Of course, commenting in your own natural language is still better than no comments at all (where appropriate), so as a last resort, use the language you are most comfortable with, and don’t be offended if another developer augments or replaces your comments.

Testing

Once a significant modification has been made, it’s a good idea to test it yourself thoroughly, without just waiting for someone else to do it for you. For SPIP, this entrails verifying that the programme works correctly on a certain number of web hosts (e.g. Altern, Free...) and with a variety of possible configurations (e.g. different versions of PHP or MySQL, greater or lesser restrictions imposed on directory access rights...) ; but also in a certain number of different situations, including those most commonly encountered in practice (especially as regards any graphical interfaces constructed) - different browsers, different operating systems, etc.

Sharing your modifications

Once you are completely satisfied with your code modifications, then it’s the right time to talk about it to other SPIP developers with an eye to evaluating if it deserves inclusion in the official SPIP distribution... Sign up to and share your news using the spip-dev distribution list. We look forward to hearing from you soon!

Footnotes

[1Yes, these examples are exaggerated by using two spaces, but that’s only so that you can clearly see what we’re trying to illustrate - please just use a single space in your own code


Show the template of this page Site powered by SPIP | Translation area | Private area