Tuleap coding standards

Code formatting

As Tuleap is mainly written in PHP, we use the PSR standards:

Rule of thumb: All new classes MUST respect PSR-2

Internal conventions

  • Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, git history…

  • It is recommended to keep lines at approximately 85-100 characters long for better code readability.

  • methodsInCamelCase()

  • $variables_in_snake_case

  • constants in UPPER_CASE

  • public methods documented (at least @return statement)

  • class documented (I'm responsible of…)

  • All added code should follow PSR-2. Existing code should be converted to PSR-2 in a dedicated commit in order to not clutter the review of your functional change.

  • No trailing whitespaces

    Note: Contributions SHOULD NOT add/fix features AND fix coding standard of a legacy file in the same review. The code WONT be accepted. If your eyes are bleeding, conform to coding standard in a dedicated review, then contribute your change.

Good quality code

Tuleap is a big (+600k LOC) and old (16 years) software and has probably an example of every existing bad designs that existed during those 16 years.

Yet, it’s not a fatality and we are on the way to, slowly and carefully clean things up. On our road toward a Clean Code, some motto might help you to make your design choices:

  • Test your code; TDD (Test Driven Development) should be the default.
  • Follow SOLID design principles.
  • Don’t contribute STUPID code.

We also strongly suggest that you familiarize yourself with Code Smells as it might pop up during code reviews.

Resources

A couple of documents worth to read when you consider contributing to Tuleap:

Tuleap principles

Output something / templating system

All new code must output content based on Mustache templates. The code is typically organized in 3 files:

  • The template
  • The presenter
  • The calling code (in a Controller for instance)

Example of template:

<h1>Hello</h1>

<p>Welcome to {{ my_title }}</p>
<!-- For readability, please note :                  -->
<!--   * the spaces between {{, variable name and }} -->
<!--   * the use of snake_case for variables         -->

Example of Presenter

class Presenter
{
    /** @var string */
    public $my_title;

    public function __construct()
    {
        $this->my_title = "My title";
    }
}

Example of calling code:

$renderer = TemplateRendererFactory::build()->getRenderer('/path/to/template/directory');

// Output content directly (to the browser for instance)
$renderer->renderToPage('template_name', new Presenter());

// Return the content for futur reuse
$string = $renderer->renderToString('template_name', new Presenter());

Attention

Known issues / limitation

Few points to keep in mind:

  • It’s recommended to use {{ }} notation to benefit from mustache automatic escaping.
  • If you have to use {{{ }}} notation, the presenter MUST deal with output escaping (with Codendi_HTMLPurifier).

Note

For existing code, it’s acceptable to output content with “echo” to keep consistency.

Secure forms against CSRF

TBD

Secure DB against SQL injections

All code related to database MUST deal with data types and do the proper escaping of values before executing the query.

Example of DataAccessObject:

namespace Tuleap/Git;

use DataAccessObject;

class RepositoryDao extends DataAccessObject
{
    public function searchByName($project_id, $name)
    {
        // project_id is supposed to be an int
        $project_id = $this->da->escapeInt($project_id);

        // name is supposed to be a string
        $name = $this->da->quoteSmart($name);

        $sql = "SELECT *
                FROM plugin_git_repositories
                WHERE project_id = $project_id
                  AND name = $name";
        return $this->retrieve($sql);
    }
}