Aller au contenu principal Aller à la navigation principale Aller au pied de page

My coding standards [en]

L’un des points les plus importants dans le métier de développeur est d’écrire du code solide, clair, facilement déboguable et compréhensible en un coup d’oeil. En tant que lead-dev, c’est le retour numéro un que je fais à mes padawans: « il est bien ce code mais si tu veux qu’il vive, suis les PSR »! Quelques règles simples pour poser les bases d’un code solide … [contenu en anglais]

Useful links

Coding styles

Base standards

I MUST try to follow the coding standards and naming rules most commonly in use:

My coding rules

  • script files MUST all be encoded with LF line ending (UNIX « linefeed ») in classic UTF-8 character set with NO BOM ;
  • lines in a script MUST never be more than 120 characters length and SHOULD NOT be more than 80 ;
  • indent is made with 4 spaces (no tab, never) ; this is true for (quite) all languages ;
  • PHP language’s keywords MUST be written all lower case
  • methods are written in camelCase: words are identified with a first capital letter and the rest in lower case ; the very first letter is NOT upper case ; a leading underscore CAN identify a special method (not only for access reason), keeping in mind that double-underscores are reserved for internal magic PHP methods ;
  • properties are written in snake_case: all lower case with words separated by underscores ; an optional leading underscore COULD identify a special access for the property (a protected or private class’ property for instance) ;
  • constants are written all upper case with underscore delimiter ;
  • the extends and implements lists COULD be written each on a new line, with indentation:
    class MyClass
        extends MyOhterClass
        implements MyInterface, MyOtherInterface
    {
    }
    

    ; this rule is NOT compliant with standards but seems to me really more efficient in practice, and compliant with the idea of lines length limit ;

  • interfaces are suffixed with Interface:
    interface MyObjectInterface
    {
    }
    
  • traits are suffixed with Trait:
    trait MyObjectTrait
    {
    }
    
  • abstarct classes are suffixed with Abstract1:
    abstract class MyObjectAbstract
    {
    }
    
  • exception classes are suffixed with Exception and extend another Exception class:
    class MyObjectException extends \Exception
    {
    }
    
  • exceptions SHOULD always have a significant message with current properties or variables which caused the error ; such message SHOULD be concatenated using the sprintf() internal function and MUST NEVER end with a punctuation:
    throw new \ErrorException(
        sprintf('%s::$proxy_class is expected to be a valid class name, "%s" given',
            get_called_class(), $this::$proxy_class)
    );
    
  • errors SHOULD follow the same rules:
    user_error(
        sprintf('Call to undefined or inaccessible method %s::%s()', get_called_class(), $name),
        E_USER_ERROR
    );
    

PHP autoloader

As I try to always use Composer for my packages, I follow the PSR-4-autoloader rules to name and store my classes.

Following these rules, I made a complete and portable fork of the original Jonathan Wage‘s SplClassLoader with a test of file existence to avoid the require error if the file does not exist. My version allows to use a classic

if (class_exists( ... ))

which does not break the original internal function purpose and usage (it may return false if the class does not exist). You can find my fork at https://gist.github.com/piwi/0e7f1560365162134725.

Common rules

@api @deprecated

Classes naming

Just like the PHP « stdClass », an object which defined a « standard » pattern or a basic minimalist object SHOULD be named prefixed by « Std ».

My « magic » methods

Just like PHP does, some commonly used methods can be identified and ruled for code homogeneity. We can first identify some « classic » access and test method names like:

get()
set()
isset() or has()
unset()

As these methods will often be defined to access some class properties, we can first try to define an automation system for these accessors using the magic PHP methods __set(), __get(), __isset() and __unset().

To be continued …


  1. this rule does not follow the PSR naming conventions but it seems to me more readable to use the Abstact string as a suffix rather than a prefix to identify quickly the scope of the object (and keep homogeneity with interfaces and traits rules). 


Laisser un commentaire

Votre adresse mail ne sera pas publiée.

Vous pouvez utiliser la syntaxe markdown dans votre commentaire.

Retour au contenu principal Retour à la navigation principale Retour à l’en-tête