Coding Standard

This document describes rules and recommendations for developing Nette. When contributing code to Nette, you must follow them. The easiest way how to do it is to imitate the existing code. The idea is to make all the code look like it was written by one person.

Nette fully follows PSR-12 Extended Coding Style with two exceptions: it uses tabs instead of spaces for indentation, and uses PascalCase for class constants.

General Rules

  • Every PHP file must contain declare(strict_types=1)
  • Two empty lines are used to seperate methods for better readability.
  • The reason for using shut-up operator must be documented: @mkdir($dir); // @ - directory may exist
  • If weak typed comparison operator is used (ie. ==, !=, …), the intention must be documented: // == to accept null
  • You can write more exceptions into one file exceptions.php
  • Interfaces do not specify method visibility because they are always public.
  • Every properties, methods and parameters must have documented type. Either natively or via annotation.
  • Arrays must be written by short notation.
  • The single quote should be used to demarcate the string, except when a literal itself contains apostrophes.

Naming Conventions

Documentation Blocks (phpDoc)

The main rule: never duplicate any signature information like parameter type or return type with no added value.

Documentation block for class definition:

  • Starts by a class description.
  • Empty line follows.
  • The @property (or @property-read, @property-write) annotations follow, one by line. Syntax is: annotation, space, type, space, $name.
  • The @method annotations follow, one by line. Syntax is: annotation, space, return type, space, name(type $param, …).
  • The @author annotation is omitted. The authorship is kept in a source code history.
  • The @internal or @deprecated annotations can be used.
/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Documentation block for property that contains only @var annotation should be in single line:

/** @var string[] */
private array $name;

Documentation block for method definition:

  • Starts by a short method description.
  • No empty line.
  • The @param annotations, one by line.
  • The @return annotation.
  • The @throws annotations, one by line.
  • The @internal or @deprecated annotations can be used.

Every annotation is followed by one space, except for the @param which is followed by two spaces for better readability.

/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabs Instead of Spaces

Tabs have several advantages over spaces:

  • indent size is customisable in editors & web
  • they do not impose the user's indentation size preference on the code, so the code is more portable
  • you can type them with one keystroke (anywhere, not just in editors that turn tabs into spaces)
  • indentation is their purpose
  • respect the needs of visually impaired and blind colleagues

By using tabs in our projects, we allow for width customization, which may seem unnecessary to most people, but is essential for people with visual impairments.

For blind programmers who use braille displays, each space is represented by a braille cell and takes up valuable space. So if the default indentation is 4 spaces, a 3rd level indentation wastes 12 braille cells before the code begins. On a 40-cell display, which is the most commonly used on laptops, that's more than a quarter of the available cells wasted without any information.