Стандарты документации

Вклады должны следовать этим стандартам, чтобы соответствовать стилю и тону остальной документации Symfony.

Sphinx

  • Для разных уровней заголовков были выбраны следующие символы: уровень 1 - = (знак равно), уровень 2 - - (дефис), уровень 3 - ~ (тильда), уровень 4 - . (точка) и уровень - 5 " (двойные кавычки);
  • Каждая строка должна прерываться примерно после первого слова, которое заходит за 72 знака (так что большинство строк будут 72-78 знаков);
  • Сокращение :: предпочитается по сравнению с .. code-block:: php, для начала блока PHP-кода (см. документацию Sphinx, чтобы узнать, когда нужно использовать сокращение);
  • Встраиваемые гиперссылки не используются. Разделяйте ссылки и их целевое описание, которое вы добавляете внизу страницы;
  • Встраиваемая разметка должна закрываться на той же строчке, что и открывающая строка кода;

Пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
Пример
======

Когда вы работаете над документами, вам нужно следовать
стандартам `Документации Symfony`_.

Уровень 2
---------

PHP-пример будет::

    echo 'Привет, мир';

Уровень 3
~~~~~~~~~

.. code-block:: php

    echo 'Вы не можете использовать сокращение :: здесь';

.. _`Документации Symfony`: https://symfony.com/doc

Примеры кода

  • Код следует Стандартам кодирования Symfony, а также Стандартам кодирования Twig;
  • Примеры кода должны выглядеть настоящими для контекста веб-приложения. Избегайте абстрактных или тривиальных примеров (foo, bar, demo, и т.д.);
  • Код должен следовать Лучшим практикам Symfony;
  • Используйте Acme, когда код требует имя поставщика;
  • Используйте example.com в качестве домена шаблонов URL, а example.org и example.net, когда требуются дополнительные домены. Все эти домены зарезервированы IANA.
  • Чтобы избежать горизонтальной прокрутки блоков кода, мы предпочитаем разрывать строчку правильно, если она превышает 85 знаков;
  • Когда вы сворачиваете одну или больше строчек кода, поместите ... в комментарии в точке сворачивания. Эти комментарии: // ... (php), # ... (yaml/bash), {# ... #} (twig), <!-- ... --> (xml/html), ; ... (ini), ... (text);
  • Когда вы сворачиваете часть строчки, например, значение переменной, поместите ... (без комментария) в точке сворачивания;
  • Описание свёрнутого кода: (необязательно)
    • Если вы сворачиваете несколько строк: описание сворачивания может быть помещено после ...;
    • Если вы сворачиваете только часть строки: описание может быть размещено перед строкой;
  • Если это полезно пользователю, пример PHP-кода должен начинаться с объявления пространства имён;
  • При ссылании на классы, убедитесь, что вы показали утверждения use сверху вашего блока кода. Вам не нужно показывать все утверждения use в каждом примере, просто покажите те, которые использются в блоке кода;
  • Если это полезно, codeblock должен начинаться с комментария, содержащего имя файла в блоке кода. Не помещайте пустую строчку после этого комментария, кроме слуаев, когда следующая строчка - тоже комментарий;
  • Вы должны помещать $ перед каждой строчкой разрыва.

Форматы

Примеры конфигурации должны отображать все поддерживаемые форматы, использующие блоки конфигурации. Поддерживаемые форматы (в их порядке):

  • Конфигурация (включая сервисы): YAML, XML, PHP
  • Маршрутизация: Аннотации, YAML, XML, PHP
  • Валидация: Аннотации, YAML, XML, PHP
  • Отображение Doctrine: Аннотации, YAML, XML, PHP
  • Перевод: XML, YAML, PHP

Пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// src/Foo/Bar.php
namespace Foo;

use Acme\Demo\Cat;
// ...

class Bar
{
    // ...

    public function foo($bar)
    {
        // установите foo со значением bar
        $foo = ...;

        $cat = new Cat($foo);

        // ... проверьте, имеет ли $bar правильное значение

        return $cat->baz($bar, ...);
    }
}

Caution

В YAML вам нужно размещать пробел после { и перед } (например, { _controller: ... }), но это не нужно делать в Twig (например, {'hello' : 'value'}).

FФайлы и каталоги

  • При ссылании на каталоги, всегда добавляйте закрывающий слэш, чтобы избежать путаницы с обычными файлами (например, "выполните скрипт console, расположенный в каталоге bin/").

  • При ссылании только на расширения файла, вам нужно включать начальную точку для каждого расширения (например, "XML файлы используют расширение .xml").

  • Когда вы перечисляете иерархию файлов / каталогов Symfony, используйте your-project/ в качестве каталога верхнего уровня. Например:

    1
    2
    3
    4
    5
    your-project/
    ├─ app/
    ├─ src/
    ├─ vendor/
    └─ ...
    

Стандарты английского языка

Документация Symfony использует английский диалект США, часто называемый американским английским. Оксфордский словарь американского английского используется в качестве словарного источника.

Кроме того, документация следует таким правилам:

  • Названия разведлов: используйте вариант капитализации начальных букв всех слов в предложении, кроме слов замкнутого класса (см. статью Википедии о заголовках и названиях).

    Например: В Моём Свежем Калифорнийском Изюме Есть Витамины

  • Пунктуация: избегайте использования серийных запятых;

  • Местоимения: избегайте использования нозизма и всегда используйте вы вместо мы. (Т.е. избегайте точки зрения первого лица: используйте второе);

  • Генденрно-нейтральный язык: при ссылании на гипотетического человека, например, "пользователя с cookie сессии", исползуйте гендерно-нейтральные местоимения (они, их, им). Например, вместо:

    • он или она, используйте они
    • ему или ей, испльзуйте им
    • его или её, используйте их

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.