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.
- Every PHP file must contain
- 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
- 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.
- Avoid using abbreviations unless the full name is excessive.
- Use uppercase for two-letter abbreviations, and pascal/camel case for longer abbreviations.
- Use a noun or noun phrase for class name.
- Class names must contain not only specificity (
Array) but also generality (
ArrayIterator). The exception are PHP attributes.
- Class constants and enums should use PascalCaps.
- Interfaces and abstract classes
should not contain prefixes or postfixes like
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.
@property-write) annotations follow, one by line. Syntax is: annotation, space, type, space, $name.
@methodannotations follow, one by line. Syntax is: annotation, space, return type, space, name(type $param, …).
@authorannotation is omitted. The authorship is kept in a source code history.
@deprecatedannotations 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.
@paramannotations, one by line.
@throwsannotations, one by line.
@deprecatedannotations can be used.
Every annotation is followed by one space, except for the
@param which is followed by two spaces for better
/** * 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.