Coding standards

SugarCRM Coding Standards

Third-party code

Any code added to the product that comes from a third-party ( that is, other than the person who is contributing the code fix and has signed a contribution agreement ) must be specifically called out in any pull request submitted to SugarCRM. Whether the code comes under a compatible open source license ( such as the BSD or MIT license ) or if the code comes from a posting on another website or forum, we must evaluate the code to be certain we can distribute without liability with the product.

Testing

All code being added or changed in the product must be covered by either a unit test written using PHPUnit or a functional test written using Soda.

Coding Standards

In order to make our code consistant and easy to read by all developers, we’ve employed the following set of standards to all newly added code. We will enforce these standards on any newly added code to the product.

• All Class names should not be capitalized, but camel-cased

Bad

<?php 

class this_isABadClassName{
...
}

Good

<?php

class ThisIsAGoodClassName
{
...
}

• All Method, Member, and Function names should not be capitalized, but camel-cased

Bad

<?php

function This_isaBadfunctionname()
{
...
}

Good

<?php

function thisIsAGoodFunctionName()
{
...
}

• Opening bracket on class, function, method names should be on the next line, justified with the class, function, method definition.

Bad

<?php

class ThisClass {
    public function newMethod(){
    }
}

function newFunction() {
}

Good

<?php

class ThisClass 
{
    public function newMethod()
    {
    }
}

function newFunction() 
{
}

• Tabs should be set at 4 spaces, and when inside a grouping structure ( class, function, method, loop, if…else block ) should have contents indented. This improves code readability.

Bad

<?php

class ThisClass
{
public $dog;

  public function eat()
  {
     if ( $this->dog ) {
return false;
}
}
}

Good

<?php

class ThisClass
{
    public $dog;

    public function eat()
    {
        if ( $this->dog ) {
            return false;
        }
    }
}

• Use public, protected, private, static keyword on class methods and members to indicate visibility. This is the new PHP standard and more clearly defines our API to developers.

Bad

<?php

class ThisClass
{
    var $_dog;

    function eat()
    {
    }
}

Good

<?php

class ThisClass
{
    protected $_dog;

    public static function eat()
    {
    }
}

• Use PHP 5 style constructors; this is the current PHP standard.
  Bad
  

  <?php
  
  class ThisClass
  {
      public function ThisClass()
      {
      }
  }

Good

<?php

class ThisClass
{
    public function __construct()
    {
    }
}

• Add PHPDoc comments for all classes/methods/members/functions. This enables us to document our API and auto-generate API documentation in the future.

Bad

<?php

class ThisClass extends OtherClass
{
    public function test($a,$b,$c)
    {
    }

    public function inherited()
    {
        parent::inherited();
    }
}

function testFunc()
{
}

Good

<?php

/**
 * Description of what this class does
 *
 * @see OtherClass
 */
class ThisClass extends OtherClass
{
    /**
     * Description of this function's functionality
     *
     * @param string $a what this does
     * @param bool $a what this does
     * @param object $a what this does
     * @return bool what this function returns
     */
    public function test($a, $b,$c)
    {
    }

    /**
     * Description of this function's functionality, if applicable to this specific version
     *
     * @see OtherClass::inherited()
     */
    public function inherited()
    {
        parent::inherited();
    }
}

/**
 * Description of this function's functionality
 *
 * @return bool what this function returns
 */
function testFunc()
{
}

• Add a license header to every new file

Good

<?php
/*********************************************************************************
 * The contents of this file are subject to the SugarCRM Professional End User
 * License Agreement ("License") which can be viewed at
 * http://www.sugarcrm.com/EULA.  By installing or using this file, You have
 * unconditionally agreed to the terms and conditions of the License, and You may
 * not use this file except in compliance with the License. Under the terms of the
 * license, You shall not, among other things: 1) sublicense, resell, rent, lease,
 * redistribute, assign or otherwise transfer Your rights to the Software, and 2)
 * use the Software for timesharing or service bureau purposes such as hosting the
 * Software for commercial gain and/or for the benefit of a third party.  Use of
 * the Software may be subject to applicable fees and any use of the Software
 * without first paying applicable fees is strictly prohibited.  You do not have
 * the right to remove SugarCRM copyrights from the source code or user interface.
 * All copies of the Covered Code must include on each user interface screen:
 * (i) the "Powered by SugarCRM" logo and (ii) the SugarCRM copyright notice
 * in the same form as they appear in the distribution.  See full license for
 * requirements.  Your Warranty, Limitations of liability and Indemnity are
 * expressly stated in the License.  Please refer to the License for the specific
 * language governing these rights and limitations under the License.
 * Portions created by SugarCRM are Copyright (C) 2004 SugarCRM, Inc.;
 * All Rights Reserved.
 ********************************************************************************/