Php add comments: How to Write Comments in PHP

PHP: Комментарии — Manual

In php there are 3 types of comments
1.single line c++ style comment(//)
2.single line Unix shell stype comment(#)
3.multi line c style comment(/*/)

single or multi line comment comes to the end of the line or come first to the current block of php code.

HTML code will be printed after //…?> or #…?>
closing tag breaks the php mode and return to html mode.

different comments in different tags:
===================================
<h2>Standard tag: <?php ?>single line c++ style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Standard tag:single line c++ style comment'</p>

<h2>Standard tag: <?php ?>single line unix shell style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Standard tag:single line unix shell style comment'</p>

<h2>Standard tag: <?php ?>multi line c style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Standard tag:multi line c style comment'</p>

  <h2>short echo tag: <?= ?>single line c++ style comment</h2>
<p>The header above will break php mode show a unexpected syntex error'</p>

  <h2>short echo tag: <?= ?>single line c++ style comment</h2>
<p>The header above will break php mode show a unexpected syntex error'</p>

  <h2>short echo tag: <?= ; ?>multiple  line c style comment</h2>
<p>The header above will break php mode show a unexpected syntex error'</p>

<h2>Short tag: <? //echo » short tag»;?>single line c++ style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Short tag:single line c++ style comment'</p>

  <h2>Short tag: <? #echo » short tag»;?>single line unix shell style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Short tag:single line unix shell style comment'</p>

   <h2>Short tag: <? /* echo » short tag»;*/?>multi line c style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Short tag:multi line c style comment'</p>

    <h2>Script tag: <script language=»php»> // echo » script tag»;</script>single line c++ style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Script tag:single line c++ style comment'</p>

    <h2>Script tag: <script language=»php»> /* echo » script tag»;*/</script>multi line c style comment</h2>
<p>The header above will break php mode and return html mode and show  ‘Script tag:multi line c style comment'</p>

    <h2>Script tag: <script language=»php»> # echo » script tag»;</script>single line unix shell style comment</h2>
<p>The header above will not break php mode </p>

Комментирование кода и генерация документации в PHP

Зачем нужны комментарии к программному коду? В каком виде их писать? Где они нужны, а где нет? Как правильно комментировать код? Как придерживаться одинакового стиля документирования всем участникам команды? Какие есть инструменты для генерации документации? В этой статье я постараюсь дать ответы на эти и другие вопросы, а также поделюсь своими мыслями по этому поводу. И поможет мне в этом кролик…

Итак, документация для программы бывает двух видов. Первая — это в самом коде программы в виде комментариев. Второй вариант — используется сторонний инструмент или отдельное место для хранения, например WIKI-движок, в котором описываются концепции работы приложения, примеры использования, взаимодействия между модулями, приводятся разные блок-схемы и диаграммы, в общем, всё то, что нельзя засунуть в код.

Варианты размещения документации

Давайте для начала рассмотрим документацию за пределами кода программы. Хотя это не есть целью данной статьи. В open source проектах нередко встречается практика, когда статьи по документации хранятся в том же репозитории, что и основной код. Например, в библиотеке для генерации фейковых фикстур для PHP документация помещена в README файл; чтоб дочитать до конца, нужно немного поскролить. Популярный HTTP-клиент для PHP Guzzle хранит инструкции по применению в разных файлах в отдельной папке docs. Хранить документацию возле кода — это, конечно, хорошо и удобно. Один раз скачав пакет вендора, у вас есть и код, и документация. Если ваша библиотека небольшая, если она стабильная и не предполагает в будущем постоянных изменений API, которые повлекут за собой постоянное переписывание документации, тогда можете смело размещать документацию в репозитории вашего проекта.

Но всё же всему есть разумный предел. Например, если вы затеяли создание собственного фреймворка, который пишется командой разработчиков, и планируете постоянные релизы, он должен быть полностью задокументирован, более того, документация должна быть переведена на несколько языков, и тогда помещать документацию в репозиторий проекта — не вариант. Потому что для документации характерны постоянные правки, доработки, переводы, исправление опечаток. Это все выливается в большое количество коммитов-фиксов, которые засоряют историю проекта. Навигация по истории коммитов, где изменения кода теряются между изменениями документации, сложна и неудобна. В таком случае лучше создать отдельный репозиторий для документации, например, как это сделали для Symfony. GitHub, GitLab, Bitbucket также предоставляют встроенный инструмент WIKI, его фишкой является то, что он прикреплен к проекту, т.е. не является самостоятельным репозиторием. Но к нему также можно обращаться через Git, т.е. стянуть себе документацию, редактировать её в удобном для себе редакторе, группировать изменения в коммиты и отправлять на сервер, так же и получать свежие правки. Вот пример хорошо оформленной WIKI для библиотеки визуализации D3.js. Конечно, же можно создать сайт для своего продукта и разместить документацию на нем. Но если вы используете какой-либо способ из перечисленных выше, то вы сможете сгенерировать веб-страницы документации из вашего Git или WIKI репозитория, инструменты для этого есть. Если вы любитель комплексных решений, обратите внимание на Confluence от Atlassian. Возможности Confluence вышли далеко за пределы обычного WIKI-движка.

Комментирование кода в коде

Теперь вернемся непосредственно к документированию кода в самом коде. Я пишу эту статью на основании собственного опыта, но после прочтения книги Роберта Мартина «Чистый код», поэтому время от времени будут встречаться умные словечки и цитаты из книги 🙂 . Первый месседж, который пытается донести нам Роберт Мартин, что комментарий — это признак неудачи. Комментарии пишутся для того, чтобы загладить вину программиста, который не смог понятно выразить свою мысль с помощью языка программирования. Процесс написания хорошего и понятного кода — материал достаточно объемный и выходит за рамки этой статьи. Но все же самое простое правило хорошего кода: пишите его так, чтоб он читался как обычные предложения. В объектно-ориентированном программировании все намного проще чем в функциональном, общепринятая практика называть классы именами существительными, а методы — глаголами, делает код более естественным. Например у нас есть кролик, опишем несколько его базовых действий в виде интерфейса:

interface RabbitInterface
{
    public function run();
    public function jump();
    public function stop();
    public function hide();
}

Опустим реализацию этого интерфейса, просто создадим новый объект от класса Rabbit:

$rabbit = new Rabbit();
$rabbit->run();
$rabbit->stop();

Код читается естественно. Метод run заставляет кролика бежать, метод stop также интуитивно понятен, он останавливает текущее действие, и кролик замирает на месте. Теперь давайте немного надрессируем животное и научим его бежать на определенное расстояние, которое будем передавать как параметр в метод run.

$rabbit->run(100);

И кролик побежал… только по коду непонятно, что означает число 100. Это минуты или метры, или сантиметры, или футы? Ситуацию исправил бы комментарий

// Rabbit have to run 100 metres
$rabbit->run(100);

Если кролик начинает «бегать» в вашем коде в нескольких местах, то каждое такое место будет нуждаться в дополнительных комментариях. Комментарии будут дублироваться и их нужно будет поддерживать в нескольких местах одновременно. Первое, что можно сделать, чтоб убрать комментарий — это заменить число на переменную.

$metres = 100;
$rabbit->run($metres);

В таком случае комментарий уже не нужен, так как читабельность чуть-чуть улучшилась, можно увидеть по коду, что кролик пробежит 100 метров. Лучшим же вариантом будет добавить контекст в название метода.

$rabbit->runInMetres(100);

Rabbit — имя существительное, run — глагол, in metres — контекст, который мы добавляем методу, чтобы он передавал суть. Пользуясь такой схемой, можно написать методы

$rabbit->runInSeconds(25);
$rabbit->runTillTime(new \DateTime('tomorrow'));
$rabbit->runTillTheEndOfForest($sherwood);

Они будут передавать суть метода, без дополнительных комментариев. Просто грамотно давайте имена переменным и методам, таким способом вы уменьшите количество необязательных комментариев в вашем коде. Роберт Мартин на этот счет дает совет:

Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, — лучше потратьте его на исправление.

Что делать, если комментарий очень большой? Как его превратить в название метода? На самом деле, не стоит бояться длинных названий методов. Длинна метода должна быть приемлемой, чтоб одновременно передавать суть и не превращать метод в нечитабельный текст. Так будет ОК:

$rabbit->runUntilFindVegetables();
$rabbit->runForwardAndTurnBackIfMeet([$wolf, $hunter]);

Но вот это уже перебор:

$rabbit->runForwardUntilFindCarrotOrCabbageAndTurnBackIfMeetWolfOrHunter();

Такой метод тяжело читать, архитектура была выбрана неправильно. Его можно зарефакторить, например, как-то так:

$conditions = new Condition();
 
$untilCondition    = (new Condition\Until())->findVegetables('carrot', 'cabbage');
$turnBackCondition = (new Condition\TurnBack())->ifMeet('wolf', 'hunter');
 
$conditions->add($untilCondition)->add($turnBackCondition);
$rabbit->run(Direction::FORWARD, $conditions);

Есть, правда, и исключения в длине названия методов. Например, когда вы пишете спеки на phpSpec, то можете не ограничивать себя в длине метода, главное, чтоб он передавал всю суть. Вот пример кода, взятого из документации phpSpec:

class MovieSpec extends ObjectBehavior
{
    function it_should_have_john_smith_in_the_cast_with_a_lead_role()
    {
        $this->getCast()->shouldHaveKeyWithValue('leadRole', 'John Smith');
    }
}

В спеках для названий методов используется запись underscore, поэтому глазу легче зацепиться за границы слов и прочитать длинное предложение. Это не по стандарту PSR, где используется camelCase, но для удобочитаемость тестов такой вариант подойдет.

Чувство меры в названиях методов приходит со временем, с опытом. Можно подсмотреть, как это делают в популярных фреймворках и библиотеках.

Характеристики комментариев

Для комментариев свойственные также следующие характеристики.

Неактуальность

Очень часто, меняя код, забывают поменять комментарий. Это особенно актуально, когда над одним участком кода трудятся несколько программистов. Комментарии есть, но они написаны одним из программистов, остальные не решаются изменить чужие комментарии либо ленятся, либо просто не обращают внимание. В результате, старый неактуальный комментарий только запутает нового человека в команде. Решение проблемы простое. Либо всегда следить за актуальностью комментариев, что потребует значительного внимания и стараний. Либо удалить неактуальный комментарий. Отсутствие комментария лучше, чем устарелый, неактуальный комментарий.

Избыточность

Это когда комментарий написан там, где он не нужен, где все понятно и без комментария. Вот пример кода, отягощенного избыточными комментариями.

// Cut the carrot into 4 pieces
$piecesOfCarrot = $carrot / 4;
// Let the rabbit eat all pieces of carrot one by one
foreach ($piecesOfCarrot as $pieceOfCarrot) {
    $rabbit->eat($pieceOfCarrot); // Rabbit eats the piece of carrot
}

Код останется абсолютно понятным, если комментарии уберем, так как код читабельный.

$piecesOfCarrot = $carrot / 4;
foreach ($piecesOfCarrot as $pieceOfCarrot) {
    $rabbit->eat($pieceOfCarrot);
}

Неполнота

Во время написания программы вы можете быстро зафиксировать свою мысль в виде комментария сразу в коде. Позже вы вернётесь к этому месту, комментарий напомнит вашу мысль, и вы сможете ее продолжить. После того, как мысль превратилась в код, неполный комментарий нужно убрать, либо превратить его в что-то более осмысленное. Другими словами, не заставляйте читателей догадываться что вы имели в виду. Например, рассмотрим процесс приема пищи кроликом:

public function eat($food)
{
    switch ($food) {
        case 'carrot':
            $this->getCalories(50);
            break;
        case 'cabbage':
            $this->getCalories(100);
            break;
        default:
            // If the rabbit eats unknown food - it dies :(
            break;
    }
}

Что означает комментарий, что «кролик умрет»? В жизни этот процесс понятен. А в программе? Что автор хотел сделать после этого? Освободить память занимаемую кроликом? Кинуть исключение и обработать его в другом месте? В данном коде с кроликом ничего не случится, он просто не получит новых калорий от поедания чего-либо, кроме морковки и капусты. Но для нового человека, который будет дописывать код, замысел автора непонятен. Скорее всего новичок удалит комментарий и сделает по-своему.

Недостоверность

Людям свойственно делать ошибки. Программисты их делают не только в коде, но и в комментариях. Либо из-за невнимательности, либо из-за усталости, либо из-за незнания иностранного языка в комментарий вносится путаница и дезинформация. К сожалению, от этого никто не застрахован. Единственное, что можно посоветовать в таком случае — это ответственно относиться к комментариям. Если вы уже решились что-то написать, то пишите грамотно. Перфекционизм в комментариях не помешает 🙂

Неочевидность

Это когда в конкретном месте кода используются неизвестные или не очевидные термины.

// Uses coefficient of rabbit growing per day, which depends on several factors
$rabbit->growInSize();

Тут указывается, что рост кролика определяется каким-то коэффициентом (сам придумал :)), который зависит от каких-то факторов. В данном месте непонятно, что означает коэффициент роста кролика и как он считается. Чтоб разобраться, как работает эта функция, все равно придется переходить в ее описание и изучать код. Лучше комментарий отсюда убрать, а разместить более детальный комментарий в описании самой функции.

Так что, комментарии вообще не писать?

Писать, но нужно брать за них ответственность. Вот моменты, когда они необходимы.

Информативность

В некоторых местах без комментариев не обойтись. Когда нужно объяснить алгоритм или когда группа программистов была вынуждена временно применить какой-то «костыль» в коде, желательно оставить комментарий об этом. Написать, зачем оно было сделано, что оно затрагивает и когда должно быть исправлено. Но все же старайтесь правильно подбирать названия вашим переменным и методам.

Регулярные выражения всегда меня вводят в ступор и приходится тратить достаточно времени, чтоб их расшифровать. В таком случае информативный комментарий не помешает:

// Find all rabbits in locations which
// end on: shire, field, wood
// starts on: yellow, green
// and are not case sensitive
// e.g. Blackshire, Greenfield, Sherwood, SHERWOOD, wood, Yellowstone
$locationsRegExp = '/\b(yellow|green)\w*|\w*(shire|field|wood)\b/i';
$rabbits = $search->findRabbitsInLocations(locationsRegExp);

Намерения

Одну и ту же задачу на языке программирования можно решить многими способами. Программист имеет собственный стиль программирования и, знакомясь с кодом другого программиста, с другим стилем, ему может быть тяжело прочитать код «по диагонали». Если вы обладаете каким-то особым стилем программирования, либо по опыту знаете, что алгоритмы, которые вы используете, тяжело читаются другими, то оставляйте в коде подсказки непосредственно перед началом сложного участка кода.

Предупреждения

Бывают случаи, когда пока каким-то причинам нельзя использовать ту или иную функцию (например, не установили еще необходимое расширение на продакшене, либо не обновил вендор), либо какая-то функция выполняется очень долго и без необходимости ее лучше не запускать, либо из-за большой потребности в ресурсах цикл нельзя выполнять более Х раз. В таких случаях комментарии будут очень полезными.

Усиление

Когда одна строка кода является настолько важной, что необходимо обратить на нее внимание. Например, однажды со мной случился случай, когда на стейджинге не была задана кодировка для мультибайтных функций, я очень долго искал проблему и когда нашел, то добавил в свой код ручную установку параметра с пояснительным комментарием для чего это нужно:

// Set default encoding for MB functions manually to prevent cases when it is missed in config
mb_internal_encoding('UTF-8');

И еще один совет от Роберта Мартина:

Не документируйте плохой код — перепишите его.

Если вам довелось встретиться с жутко непонятным кодом, вы потратили много времени на его разбор, а после решили добавить от себя пару комментариев для будущих разработчиков, то код от этого лучше не станет. В этой ситуации, раз вы уже достаточно разобрались с кодом, попробуйте зарефакторить его до более читабельного состояния. Правило бойскаута гласит: «оставьте место (код) чище, чем было до вашего прихода».

Документируем с помощью докблоков

Есть отдельный вид комментариев в PHP, который имеет свой устоявшийся стандарт — это докблоки (DocBlock). Для обработки докблоков существует инструмент phpDocumentor (ранее известен как phpDoc). Он умеет читать докблоки из кода и строить на их основе документацию. DocBlock — это комбинация DocComment и помещенных в него описаний по стандарту PHPDoc. В PHP есть поддержка C-подобных многострочных комментариев (DocComment):

/*
 * It is
 * a C-style comment in PHP
 */

Докблок отличается дополнительной звездочкой /** в начале комментария:

/**
 * It is
 * a PHP docblock
 */

Докблоком может быть и одна строка, главное, чтоб она начиналась с /**.

/** It is also a docblock */

Стандарт PHPDoc для документирования PHP-кода был реализован на основе уже существующего javaDoc для языка Java. Важной составляющей докблоков являются теги и аннотации, которые предают комментариям семантическую окраску. Тег или аннотация начинается с символа @, например:

/**
 * Login via email and password
 *
 * @param Request $request Request
 *
 * @return Response
 *
 * @throws BadRequestHttpException
 * @throws UnauthorizedHttpException
 *
 * @Rest\Post("/login")
 */
public function loginAction(Request $request)
{
}

В данном примере @param, @return, @throws являются тегами PHPDoc и будут распрарсены с помощью phpDocrumentor’а. @Rest\Post("/login") — это аннотация FOSRestBundle. Отличие аннотаций от тегов в том, что теги просто документируют код, а аннотации меняют или добавляют поведение для кода. Отличительная черта аннотаций PHP от аннотаций Java, в том, что в Java аннотации являются частью языка, а в PHP — всего лишь комментариями, и чтоб к ним достучаться приходиться использовать рефлексию. Возможно в будущем аннотации также станут частью PHP, а пока для их считывания используется вот этот парсер https://github.com/phpDocumentor/ReflectionDocBlock. Так же стоит заметить, что если мы изменим начало докблока с /** на /* это уже не будет считаться докблоком, даже если там есть теги или аннотации, соответственно парсер проигнорирует это место.

Докблоки настолько прижились в коммюнити PHP-программистов, что на их основе готовится PSR-5 (PHP Standard Recommendation). На момент написания статьи он еще находился в черновом варианте.

В PHP с помощью докблоков можно документировать такие элементы:

• функции;
• константы;
• классы;
• интерфейсы;
• трейты;
• константы классов;
• свойства;
• методы.

Важно также, что один докблок может быть применён только к одному структурному элементу. Т.е. на каждую функцию — свой докблок, на переменную внутри функции — свой, для класса — свой.

/**
 * Rabbit Class
 *
 * @version 0.1.0
 */
class Rabbit implements RabbitInterface
{
    const STATUS_RUNNING = 'running';
 
    /**
     * @var string $status Status
     */
    private $status;
 
    /**
     * Set `running` status for the rabbit
     *
     * @return $this
     */
    public function run()
    {
        $this->status = self::STATUS_RUNNING;
 
        return $this;
    }
}

В PHPDoc существует много тегов, но не каждый тег применим ко всем структурным элементам. Ниже предоставлен список существующих тегов, область их использования и объяснение.

• @api (метод) — обозначает стабильные публичные методы, которые не будут менять свою семантику до следующего мажорного релиза.
• @author (в любом месте) — указывает имя и имейл автора, который написал следующий код.
• @copyright (в любом месте) — используется, чтоб поставить свой копирайт в коде.
• @deprecated (в любом месте) — полезный тег, символизирует, что данный элемент исчезнет в будущих версиях. Обычно рядом пишут, какой код следует использовать взамен. Также большинство IDE подсвечивают использование устаревших методов отдельным стилем. Когда нужно подчистить устаревший код для нового релиза, то легко искать по этому тегу.
• @example (в любом месте) — используется для размещения ссылки на файл или веб-страницу, где показан пример использования кода. На данный момент phpDocumentor заявляет о неполной поддержки возможностей этого тега.
• @filesource (файл) — этот тег можно размещать только на самом начале php-файла, так как тег применим только к файлу и включит весь код файла в сгенерированную документацию.
• @global (переменная) — на данный момент этот тег не поддерживается, возможно, будет реализован в следующих версиях, когда он будет переосмыслен.
• @ignore (в любом месте) — докблок, где указан этот тег, не будет обрабатываться во время генерации документации, даже если в нем есть другие теги.
• @internal (в любом месте) — чаще всего используется вместе с тегом @api, чтоб показать, что код предназначен для внутренней логики этой части программы. Элемент, обозначенный этим тегом, не будет включен в документацию.
• @license (файл, класс) — что же он еще может делать, если не указывать тип лицензии для написанного кода.
• @link (в любом месте) — используется для вставки ссылок, но, как пишет документация, полностью функциональность тега пока не поддерживается.
• @method (класс) — применяется к классу и служит для описания магических методов, которые обрабатываются магической функцией __call().
• @package (файл, класс) — разбиение кода на логические подгруппы. Когда вы помещаете классы в один namespace, вы тем самым показывает их функциональную схожесть. Если классы лежат в разных неймспейсах, но имеют одинаковый логический признак, их можно сгруппировать с помощью этого тега, например, если у вас классы работающие с корзиной заказа разбросаны по разным местам. Но лучше отказаться от такой практики, по код стайлу Symfony, например, этот тег не должен использоваться.
• @param (метод, функция) — предназначен для описания входящих параметров функции. Важно также отметить, что если вы уже взялись описывать входящие параметры для конкретной функции через докблоки, то нужно описывать все, а не только первый или второй.
• @property (класс) — так же, как и @method, этот тег размещается в докблоке для класса, но описывает свойства, доступ к которым будет обрабатываться через магические методы __get() и __set().
• @property-read, @property-write (класс) — аналогично предыдущему тегу, но обрабатывают только один магический метод, __get() или __set() соответственно.
• @return (метод, функция) — предназначен для описания значения, которое возвращает функция. Можно указать его тип, и PhpStorm подхватит его и будет выдавать подсказки, но об этом чуть позже.
• @see (в любом месте) — с помощь этого тега можно вставлять ссылки на внешние ресурсы, как и с помощью @link, но также вставлять относительные ссылки на классы и методы.
• @since (в любом месте) — можно указать версию, в которой появился кусок кода.
• @source (в любом месте, кроме начала файла) — с помощью этого тега можно помещать в документацию участки исходного кода (задается строка начала и конца).
• @throws (метод, функция) — используется для указания исключений, которые могут быть вызваны в данной функции.
• @todo (в любом месте) — самый оптимистически тег, используется программистами, чтоб напомнить себе доделать что-то, когда-то в каком-то участке кода. IDE умеют распознавать этот тег и группируют все участки кода в отдельном окне, удобно для будущего поиска. Это общепринятый стандарт и используется очень часто.
• @uses (в любом месте) — предназначен для отображения связи между разными участками кода. Он чем-то похож на @see, но разница в том, что @see создает однонаправленную ссылку, т.е. после перехода на новую страницу документации у вас не будет ссылки назад, а @uses в процессе его обработки ставит обратную ссылку, т.е. ссылку для обратной навигации.
• @var (переменная) — используется для указания типа и описания переменных, как тех, что встречаются внутри функций, так и свойств класса. Следует учесть разницу между этим тегом и тегом @param. Тег @param используется только в докблоках для функций и описывает входящие параметры, а @var используется для документирования обычных переменных.
• @version (в любом месте) — обозначает текущую версию программы, в которой появился данный класс, метод и т.д.

Устаревшие теги, которые, скорее всего, в будущем не будут поддерживаться:

• @category (файл, класс) — использовался для группирования пакетов вместе.
• @subpackage (файл, класс) — использовался для выделения определенных групп в пакетах.

Не все теги одинаково популярны, чаще всего используются: @var, @param, @return, @todo, @throws, остальные — реже. А такие, как @property и @method я вообще еще не встречал в применении, потому что «работать с магией» в PHP — опасно 🙂

Удобство использования докблоков в IDE

Если вы разрабатываете open source проект, то конечно документирование публичного API с помощью докблоков необходимо. Это не только позволит вам сгенерировать готовую документацию, но также позволит использовать ваш код удобно другим разработчикам в своих IDE. Что касается вашего приватного кода для аутсорс проекта, то использование докблоков может показаться не очень уместным, тем не менее советую их использовать, это значительно ускорит вашу разработку.

Для примера возьмем самую популярную IDE для PHP — PhpStorm. Рассмотрим предыдущий пример поиска кроликов:

$rabbits = $search->findRabbitsInLocations('/Sherwood/');
foreach ($rabbits as $rabbit) {
    $rabbit->doSomething();
}

Что хранят в себе переменные $rabbits и $rabbit? PhpStorm об этом ничего не знает. PHP — язык слабо типизированный, тип результата функции не задается жестко из ее описания (привет PHP7, где это будет реализовано). Поэтому вашей IDE нужно подсказать с помощью докблоков, как вести себя с тем или иным кодом. Вариантов есть несколько. Можно сделать так:

/** @var Rabbit $rabbit */
foreach ($rabbits as $rabbit) {
    $rabbit->doSomething();
}

Или добавить тег @return в метод findRabbitsInLocations:

/**
 * @return Rabbit[]
 */
public function findRabbitsInLocations($locations)
{
    // some operations here...
    return [];
}

Обратите внимание, что мы указали Rabbit[], а не Rabbit. Квадратные скобки дают понять, что возвращается массив объектов класса Rabbit, если квадратные скобки убрать, то это будет означать, что метод возвращает один экземпляр класса Rabbit. Еще можно написать так @return null|Rabbit[], вертикальная палка означает «ИЛИ», в данном случае мы указываем, что метод вернет либо массив кроликов, либо null.

Независимо от того, какой способ указания типа вы выбрали, PhpStorm теперь будет выдавать вам подсказки, когда вы напечатаете $rabbit-> и подождете мгновение:

Так происходит потому, что PhpStorm знает, что в переменную $rabbits возвращается массив объектов класса Rabbit. Далее в цикле foreach переменная $rabbit получает один элемент массива, который является экземпляром класса Rabbit и PhpStorm показывает вам доступные публичные методы из этого класса.

Таким образом, не отрываясь от клавиатуры, вы можете использовать классы с публичными методами, которые написали ваши коллеги. PhpStorm будет выдавать вам подсказки, и если метод назван понятно, вы сможете использовать его даже без чтения его исходного кода и документации.

Еще одна полезная фича докблоков в паре с PhpStorm — это предупреждения о неправильных входных параметрах. Допишем докблок для одного из методов класса Rabbit:

/**
 * Run in metres
 *
 * @param int $metres Metres
 */
public function runInMetres($metres)
{
    // some operations here...
}

Тут мы указываем, что на вход должно приходить целое число (опять же, в PHP7 это возможно будет задать на уровне синтаксиса самого языка). Что будет, если мы передадим в этот метод массив?

PhpStorm выделит цветом и выдаст вам подсказку, что на вход ожидается int, а вы передает array. Удобно, правда? Так же подсказки будут выдаваться и на несоответствие классов, интерфейсов. Если ваш метод поддерживает несколько типов для входящих аргументов, то разделите их также через |. В данном примере, если метод runInMetres() также умеет обрабатывать массивы, то в докблок можно дописать «@param int|array $metres Metres» и PhpStorm перестанет ругаться.

PhpStorm также умеет сам генерировать докблоки. Поставте курсор строкой выше на объявление функции, класса или переменной, наберите /** и нажмите Enter, IDE сгенерит вам докблок по шаблону, по желанию можно подправить. Также генерацию докблоков можно запустить через Alt + Insert.

Как соблюдать стили комментирования

Это хорошо, если все участники команды соблюдают правила документации для PHPDoc. Но все же на практике все намного печальнее. Полностью соблюдать стандарт получается только у перфекционистов, либо у тех, кто долго пользуется докблоками и это у них автоматизировано. Есть категория программистов-новичков, которые хотят использовать докблоки, но забывают их иногда использовать, либо еще не полностью разобрались с тем или иным тегом. Ну конечно же, есть упертые люди, которые не делают это, даже если предварительно команда согласилась делать.

Чтоб минимизировать дискомфорт, нужно заставить каждого участника команды включить в PhpStorm инспекцию докблоков и отметить там все галочки:

Так же следует использовать PHP CodeSniffer (phpcs) с подходящим вам код стайлом. Не уверен, как насчет всех код стайлов, но для Symfony докблоки являются обязательными. Поэтому phpcs в Шторме будет выдавать вам предупреждения на лету. Настройки делаются в том же месте, а вот еще есть дополнительная инструкция.

Конечно это не заставит всех на 100% придерживаться правил. Но особенных ленивцев можно нагрузить еще одной цитатой из книги «Чистый код», правда, это больше относиться к форматированию кода, но смысл тот же:

«Правила должны соблюдаться всеми участниками группы. Это означает, что каждый участник группы должен быть достаточно разумным, чтобы понимать: неважно, как именно размещаются фигурные скобки, если только все согласились размещать их одинаковым образом.»

Генерация документации с помощью phpDocumentor

Теперь, когда все придерживаются правил, и ваш код покрыт докблоками, можно сгенерировать документацию. Приводить всю документацию по phpDocumentor не буду, всего лишь минимум команд, остальное на официальном сайте.

Итак, нужно установить phpDocumentor. Его можно поставить глобально вот так:

$ wget http://www.phpdoc.org/phpDocumentor.phar
$ chmod +x phpDocumentor.phar
$ sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
$ phpdoc --version

Либо добавить как зависимость в composer.json вашего проекта.

$ composer require --dev "phpdocumentor/phpdocumentor:2.*"

А теперь, находясь в директории проекта, который вы покрыли докблоками, просто запустите из консоли:

$ phpdoc -d src/

Как я и упоминал, это самый минимальный набор действий для генерации документации, опция -d src/ указывает на путь к файлам, которые вы хотите обработать. Сгенерированная документация будет создана в папке output. Конечно же, у этой утилиты есть разные параметры и она умеет разные штуки. А выглядеть сгенерированная документация будет так, можно выбрать существующий шаблон или создать свой.

Генерация документации с помощью Sami

Еще один инструмент для генерации php-документации на основе докблоков — утилита Sami. Возможно, она не такая известная, но я решил ее упомянуть, так как с помощью Sami генерируется документация нашей любимой Symfony.

Seoaction.net — seo и не только…

Тег | htmlbook.ru

Спецификация

Описание

Поле <textarea> представляет собой элемент
формы для создания области, в которую можно вводить несколько строк текста.
В отличие от тега <input> в текстовом поле допустимо
делать переносы строк, они сохраняются при отправке данных на сервер.

Между тегами <textarea> и </textarea> можно поместить любой текст, который будет отображаться внутри поля.

Синтаксис

<textarea атрибуты>
  текст
</textarea>

Атрибуты

accesskey

Переход к полю с помощью сочетания клавиш.

autofocus

Автоматическое получение фокуса.

cols

Ширина поля в символах.

disabled

Блокирует доступ и изменение элемента.

form

Связывает текстовое поле с формой по её идентификатору.

maxlength

Максимальное число введенных символов.

name

Имя поля, предназначено для того, чтобы обработчик формы мог его идентифицировать.

placeholder

Указывает замещающийся текст.

readonly

Устанавливает, что поле не может изменяться пользователем.

required

Обязательное для заполнения поле.

rows

Высота поля в строках текста.

tabindex

Порядок перехода между элементами при нажатии на клавишу Tab.

wrap

Параметры переноса строк.

Также для этого тега доступны универсальные атрибуты и события.

Закрывающий тег

Обязателен.

Пример

HTML5IECrOpSaFx

<!DOCTYPE HTML>
<html>
 <head>
  <meta charset="utf-8">
  <title>Тег TEXTAREA</title>
 </head>
 <body>

  <form action="textarea1.php" method="post">
    <p><b>Введите ваш отзыв:</b></p>
    <p><textarea rows="10" cols="45" name="text"></textarea></p>
    <p><input type="submit" value="Отправить"></p>
  </form>

 </body>
</html>

PHP: Комментарии — Руководство

В php есть 3 типа комментариев
1. однострочный комментарий в стиле c ++ (//)
2. однострочный комментарий в стиле оболочки Unix (#)
3. многострочный комментарий в стиле c (/ * /)

однострочный или многострочный комментарий доходит до конца строки или идет первым в текущем блоке php-кода.

HTML-код будет напечатан после // …?> Или # …?> Закрывающий тег
прерывает режим php и возвращается в режим html.

разных комментариев в разных тегах:
===================================

Стандартный тег :

однострочный комментарий в стиле c ++

Заголовок выше нарушит режим php и вернет режим html и покажет «Стандартный тег: однострочный комментарий в стиле c ++»

Стандартный тег:

Однострочный комментарий в стиле оболочки unix

Заголовок выше нарушит режим php и вернет режим html и покажет «Стандартный тег: однострочный комментарий в стиле оболочки unix»

Стандартный тег:

Многострочный комментарий в стиле c

Заголовок выше нарушит режим php, вернет режим html и покажет ‘Стандартный тег: многострочный комментарий в стиле c’

короткий эхо-тег:

однострочный комментарий в стиле c ++

Заголовок выше прервет режим php покажет неожиданную ошибку syntex ‘

короткий эхо-тег:

однострочный комментарий в стиле c ++

Заголовок выше нарушит режим php, покажет неожиданный синтекс e rror ‘

короткий эхо-тег:

комментарий в стиле c, состоящий из нескольких строк

Заголовок выше нарушит режим php и покажет неожиданную ошибку syntex ‘

Короткий тег:

однострочный комментарий в стиле c ++

Заголовок выше прервет режим php и вернет режим html и покажет «Короткий тег: однострочный комментарий в стиле c ++»

Короткий тег:

однострочный комментарий в стиле оболочки unix

Приведенный выше заголовок нарушит режим php и вернет режим html и покажет «Короткий тег: однострочный комментарий в стиле оболочки unix»

Короткий тег:

многострочный комментарий в стиле c

Заголовок выше прервет режим php, вернет режим html и покажет «Короткий тег: многострочный комментарий в стиле c»

Тег сценария:

однострочный комментарий в стиле c ++

Заголовок выше нарушит режим php и верните режим html и покажите ‘Тег сценария: однострочный комментарий в стиле c ++’

Тег сценария:

Многострочный комментарий в стиле c

Заголовок выше прервет режим php и вернет режим html и покажет «Тег сценария: многострочный комментарий стиля c»

Тег сценария:

однострочный комментарий в стиле оболочки unix

Заголовок выше не нарушит режим php

Добавление комментариев

Добавление комментариев

PDT позволяет
вы можете быстро и легко комментировать и раскомментировать код, выбрав строку
или блок текста и пометить его как комментарий.

Комментарии могут быть добавлены к отдельным строкам кода ( Ctrl
+ / ) или блоки кода ( Ctrl +
Shift + / ).

Кроме того, могут быть добавлены специальные комментарии PHPDocBlock. См. «Добавление комментариев PHP DocBlock»
для дополнительной информации.

Следующие процедуры описывают, как комментировать
и раскомментируйте строки и блоки кода.

Как и зачем писать комментарии в PHP-коде

Комментарий в PHP-коде — это строка, которая не читается как часть программы. Его единственная цель — быть прочитанным кем-то, кто редактирует код. Так зачем использовать комментарии?

• Чтобы сообщить другим, что вы делаете .Если вы работаете с группой людей или планируете, что кто-то еще когда-либо будет использовать ваш сценарий, комментарии сообщают другим программистам, что вы делали на каждом этапе. Это значительно упрощает им работу и редактирование вашего кода, если это необходимо.
• Чтобы напомнить себе, что вы сделали. Хотя вы, возможно, просто пишете небольшой сценарий для себя и не видите необходимости в комментариях, все равно добавьте их. Большинство программистов через год или два возвращались, чтобы отредактировать свою работу, и им приходилось выяснять, что они сделали.Комментарии могут напоминать вам о ваших мыслях, когда вы писали код.

Есть несколько способов добавить комментарий в PHP-код. Первый — использовать // , чтобы закомментировать строку. Этот стиль однострочного комментария комментирует только конец строки или текущий блок кода, в зависимости от того, что наступит раньше. Вот пример:

  эхо «привет»;  

  // это комментарий  

  эхо «там»;  

 ?>  

Если у вас однострочный комментарий, другой вариант — использовать знак #.Вот пример этого метода:

эхо «привет»;

# это комментарий

эхо «там»;

?>

Если у вас более длинный многострочный комментарий, лучше всего использовать / * и * / до и после длинного комментария. Вы можете содержать несколько строк комментариев внутри блока. Вот пример:

  эхо «привет»;  

  / *  

  Используя этот метод  

  вы можете создать более крупный блок текста  

 , и все будет закомментировано  

  * /  

  эхо «там»;  

 ?>  

Не смешивайте комментарии

Хотя вы можете вкладывать комментарии в комментарии в PHP, делайте это осторожно.Не все из них одинаково хорошо гнездятся. PHP поддерживает комментарии в стиле оболочки C, C ++ и Unix. Комментарии в стиле C заканчиваются первым знаком * /, поэтому не вкладывайте комментарии в стиле C.

Если вы работаете с PHP и HTML, имейте в виду, что комментарии HTML ничего не значат для анализатора PHP. Они не будут работать должным образом и, скорее всего, будут выполнять какую-то функцию. Итак, держитесь подальше от:

MySQL: комментарии в SQL

Это руководство по MySQL объясняет, как использовать комментарии в операторах SQL в MySQL, с синтаксисом и примерами.

Описание

Знаете ли вы, что вы можете помещать комментарии в свои операторы SQL в MySQL? Эти комментарии могут отображаться в одной строке или занимать несколько строк. Давайте посмотрим, как это сделать.

Синтаксис

Есть три синтаксиса, которые вы можете использовать для создания комментария в вашем операторе SQL в MySQL.

Синтаксис

с использованием символа

#

Синтаксис для создания комментария SQL в MySQL с использованием символа # :

 #  комментарий идет сюда  

В MySQL комментарий, начинающийся с символа # , должен находиться в конце строки в вашем операторе SQL с разрывом строки после него.Этот метод комментирования может охватывать только одну строку в вашем SQL и должен находиться в конце строки.

Синтаксис

с использованием символа

-

Синтаксис для создания комментария SQL в MySQL с использованием символа - :

 -  комментарий здесь  

В MySQL комментарий, начинающийся с символа - , аналогичен комментарию, начинающемуся с символа # . При использовании символа - комментарий должен находиться в конце строки в вашем операторе SQL с разрывом строки после него.Этот метод комментирования может охватывать только одну строку в вашем SQL и должен находиться в конце строки.

Синтаксис

с использованием символов

/ * и * /

Синтаксис для создания комментария SQL в MySQL с использованием символов / * и * / :

 / *  здесь идет комментарий  * / 

. В MySQL — комментарий, который начинается с символа / * и заканчивается на * / и может находиться в любом месте вашего оператора SQL.Этот метод комментирования может охватывать несколько строк в вашем SQL.

Пример — комментарий в одной строке

Вы можете создать комментарий SQL в отдельной строке вашего оператора SQL в MySQL.

Давайте посмотрим на пример комментария SQL, который показывает комментарий SQL, который находится в одной строке и не занимает несколько строк.

 ВЫБЕРИТЕ contact_id, last_name, first_name
/ * Автор: TechOnTheNet.com * /
ОТ контактов; 

Вот комментарий SQL, который появляется в середине строки:

 SELECT / * Автор: TechOnTheNet.ru * / contact_id, last_name, first_name
ОТ контактов; 

Вот комментарий SQL, который появляется в конце строки:

 ВЫБЕРИТЕ contact_id, last_name, first_name / * Автор: TechOnTheNet.com * /
ОТ контактов; 

или

 ВЫБЕРИТЕ contact_id, last_name, first_name - Автор: TechOnTheNet.com
ОТ контактов; 

или

 ВЫБЕРИТЕ contact_id, last_name, first_name # Автор: TechOnTheNet.com
ОТ контактов; 

Пример — комментарий к нескольким строкам

В MySQL вы можете создать комментарий SQL, который занимает несколько строк в вашем операторе SQL.Например:

 ВЫБЕРИТЕ contact_id, last_name, first_name
/ *
 * Автор: TechOnTheNet.com
 * Цель: показать комментарий, занимающий несколько строк в вашем SQL.
 * оператор в MySQL.
 * /
ОТ контактов; 

Этот комментарий SQL занимает несколько строк в MySQL — в этом примере он занимает 5 строк.

В MySQL вы также можете создать комментарий SQL, который занимает несколько строк, используя следующий синтаксис:

 ВЫБЕРИТЕ contact_id, last_name, first_name / * Автор: TechOnTheNet.ком
Цель: показать комментарий, занимающий несколько строк в вашем операторе SQL. * /
ОТ контактов; 

MySQL будет считать, что все, что находится после символа / * , является комментарием, пока не достигнет символа * / , даже если оно занимает несколько строк в операторе SQL. Таким образом, в этом примере комментарий SQL будет занимать 2 строки в операторе SQL.

комментариев PHPDoc | IntelliJ IDEA

Следующее действительно только тогда, когда плагин PHP установлен и включен.

Для комментариев документации IntelliJ IDEA предоставляет автозавершение, которое включено по умолчанию. IntelliJ IDEA создает заглушки блоков PHPDoc, когда вы вводите открывающий тег / ** и нажимаете , вводите или нажимаете Alt + Insert и назначаете конструкцию кода (класс, метод, функцию и т. Д.) задокументировать. В зависимости от вашего выбора IntelliJ IDEA создаст необходимые теги или добавит пустую заглушку документации.

Если вам нужны дополнительные теги, специфичные для PHP, IntelliJ IDEA предоставляет автозавершение кода, которое предлагает имена тегов, релевантные в текущем контексте.Если определенный тег имеет несколько значений, завершение кода предоставляет список доступных значений.

В комментариях PHPDoc IntelliJ IDEA поддерживает параметры форматирования в соответствии с ZEND, PEAR и другими стандартами кодирования.

Комментарии PHPDoc в исходном коде доступны для быстрого поиска в документации, который помогает быстро получить информацию для любого задокументированного символа. Вы можете открыть их для просмотра в окне инструмента документации, нажав Ctrl + Q .

Включить комментарии к документации

1. Нажмите Ctrl + Alt + S , чтобы открыть настройки IDE и выбрать Editor | Общие | Умные ключи.

2. В разделе «Ввод» установите или снимите флажок «Вставить заглушку комментария к документации».

3. Следующее действительно только тогда, когда подключаемый модуль Python установлен и включен.

   Для Python: разверните узел Smart Keys и выберите Python. При необходимости используйте заполнители типа Insert в параметре заглушки комментария документации. Подробную информацию см. В описании опции.

Создать блок PHPDoc для конструкции кода

1. Чтобы вызвать создание блока PHPDoc, выполните одно из следующих действий:

   • Поместите курсор перед требуемой конструкцией кода (класс, метод, функция и так далее), введите комментарий к открывающему блоку / ** и нажмите Введите .

   • В контекстном меню редактора выберите и выберите конструкцию кода, для которой будут созданы комментарии PHPDoc.

   • Нажмите Alt + Insert , затем выберите «Создать блоки PHPDoc» и выберите конструкцию кода, для которой будут созданы комментарии PHPDoc.

   IntelliJ IDEA анализирует назначенную конструкцию кода, извлекает данные для параметров, возвращаемых значений, переменных или полей, где это возможно, и на этой основе генерирует заглушку блока документации.

2. При необходимости опишите перечисленные параметры и возвращаемые значения. IntelliJ IDEA проверяет и обрабатывает синтаксис в комментариях в соответствии с настройками проверки кода.

Создание тегов в блоке комментариев PHPDoc

IntelliJ IDEA анализирует назначенную конструкцию кода, извлекает данные для параметров, возвращаемых значений, переменных или полей, где это возможно, и на этой основе создает заглушку блока документации. При необходимости вы можете заполнить недостающую информацию.

1. В блоке PHPDoc выберите нужную пустую строку и нажмите Ctrl + Пробел .

2. Выберите соответствующий тег из списка предложений.

3. Если введенный тег имеет несколько значений, нажмите Ctrl + Пробел и выберите нужное значение из списка предложений.

Настройте форматирование внутри комментариев PHPDoc

Вы можете настроить внешний вид комментариев PHPDoc, представление имен классов и порядок сортировки тегов по умолчанию.Обратите внимание, что тег свойств больше не настраивается, тег @var по умолчанию вставляется автоматически. Подробнее см. Https://github.com/phpDocumentor/fig-standards/pull/55.

1. В диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S перейдите к.

2. Переключитесь на вкладку PHPDoc и настройте желаемые параметры внешнего вида, установив или сняв флажки.

3. Укажите, как вы хотите, чтобы IntelliJ IDEA представляла имена классов для свойств, параметров функций, возвращаемых и генерируемых значений и т. Д., Установив или сняв флажок Использовать полностью определенные имена классов.

4. При необходимости определите способ сортировки сгенерированных тегов PHPDoc, установив флажок «Сортировать теги PHPDoc».

   Обратите внимание, что теги PHPDoc, которые не добавлены в список, будут сгенерированы под перечисленными.

Использование проверок кода PHPDoc

IntelliJ IDEA предоставляет набор предопределенных проверок кода, нацеленных на блоки PHPDoc. Эти проверки проверяют, поставляются ли классы, методы, функции, переменные и константы с комментарием PHPDoc и соответствуют ли теги в комментарии документированному элементу.

Включение или отключение проверки PHPDoc

1. В диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S выберите.

2. На открывшейся странице Inspections разверните узел PHPDoc в разделе PHP.

3. В открывшемся списке предопределенных проверок включите или отключите проверку, установив или сняв флажок рядом с ней.

Убедитесь, что комментарии PHPDoc предоставлены для конструкций кода определенного типа.

1. Включите проверку отсутствия комментариев PHPDoc.

2. В области «Параметры» установите флажки рядом с нужным типом элемента: классом, методом, функцией, переменной или константой.

   Чтобы подавить сообщение об ошибке «Отсутствует комментарий PHPDoc», если метод или функция не содержит никаких параметров или возвращаемых значений, установите флажок «Игнорировать PHPDoc без @ param / @ return».

Последнее изменение: 8 марта 2021 г.

Комментарии в PHP — Учебное пособие — Программирование в нерабочее время

Мы подошли к краеугольному камню всех языков, включая PHP, комментарии .Я не могу подчеркнуть важность комментирования вашего кода. Как веб-мастер, я создаю всевозможные веб-приложения, но, что более важно, я поддерживаю код, созданный до того, как я пришел. Так много раз я задавался вопросом: «Что, черт возьми, они здесь делают?»… И примерно через 10-20 минут переваривания своего кода я действительно понимаю, чего они пытались достичь. Пожалуйста, прокомментируйте. Пожалуйста. С учетом сказанного, постарайтесь не слишком комментировать. Это нормально делать это каждые несколько строк, начиная с новичка.Однако, когда вы станете более продвинутыми, попробуйте комментировать большие разделы (каждую функцию и по крайней мере каждые 30 строк) и объяснить, что вы делаете, в следующем коде.

Хватит лекций, как мне вообще прокомментировать? Комментировать очень просто, как и на других языках. В PHP вы можете делать комментарии двумя способами.

Комментарий в одной строке

Пример

// echo «Я классный!»;
#echo «Я классный!»;
echo «Я действительно классный!»;
?>

Результат Я действительно классный!

Очевидно, // комментарии только до точки с запятой или до конца строки.Не требует заключительного партнера. # Работает точно так же, как и предыдущий комментарий. Другой тип комментария — это блочный комментарий, который позволяет закомментировать более одной глупой строки. Он позволяет комментировать сколько угодно.

Многострочный комментарий

Пример

/ * echo «Я потрясающий!»;
echo «Я действительно классный!»;
* /
echo «Я супер крутой!»;
?>

Результат Я супер крутой!

Для / * требуется закрывающий тег * /.Все, что находится между этими тегами, полностью игнорируется как код PHP. Этот комментарий идеально подходит для тестирования вашего кода, блокировки кода, который сейчас не нужен, и написания абзаца о том, что должен делать ваш следующий код.

комментариев — Социальные плагины — Документация

Комментарии Модерация

Часть плагина комментариев является мощным инструментом модерации. Этот инструмент позволяет вашей команде управления сообществом легко и быстро модерировать сразу несколько комментариев.

Настройка

Чтобы использовать инструмент модерации комментариев, вам необходимо выполнить инструкции по настройке модерации.

Инструкции по настройке модерации

Обратите внимание, что вы не можете использовать Graph API для ответа на комментарии, сделанные через плагин комментариев.

Панель приборов

Есть 2 способа перейти к инструменту модерации:

1. Просмотр модерации на основе приложения: Перейдите на developers.facebook.com/tools/comments. Вы получите список всех ваших приложений Facebook, который позволит вам модерировать все комментарии, связанные с каждым приложением.Если вы не используете приложение Facebook со своим плагином комментариев, вы не сможете использовать это представление.

2. Просмотр модерации на основе страниц: Щелкните ссылку Moderation Tool рядом с полем для комментариев (см. Снимок экрана ниже). В представлении отображаются только комментарии, размещенные на этой веб-странице (URL).

Просмотр модерации

Мы показываем оба режима модерации на скриншотах ниже. Если вы используете режим модерации на основе приложения, вы можете использовать меню для переключения между приложениями.

В таблице модерации вы можете одобрить или скрыть комментарии в зависимости от их статуса. Чтобы изменить статус нескольких комментариев, используйте флажки в левом столбце.

1. Просмотр модерации на основе страницы

В этом режиме модерации будут отображаться все комментарии для определенного URL.

2. Просмотр модерации на основе приложения

В этом режиме просмотра будут отображаться все комментарии к вашей заявке.

3.Отмеченная очередь

Здесь будут отображаться комментарии, отмеченные пользователями или Facebook. Комментарии в этом списке могут быть общедоступными или скрытыми в зависимости от настроек приложения и того, как был отправлен комментарий.

4. Моя очередь

Чтобы лучше разделить работу между разработчиками, вы можете использовать эту функцию, чтобы назначать себе комментарии для модерации. Комментарии, назначенные здесь, по-прежнему будут доступны другим модераторам или администраторам, но комментарии в вашей очереди не появятся в очередях других.

Настройки

Для каждого приложения вы можете определить собственные настройки. Используйте кнопку Settings (в правом верхнем углу инструмента), чтобы открыть диалоговое окно настроек.

Модераторы

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

Сортировать комментарии по

Вы также можете управлять сортировкой комментариев.Дополнительные сведения см. В разделе «Сортировка комментариев».

Модерация

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

Есть три разных режима модерации:

Общественный

Все комментарии будут общедоступными. Они также появятся на вкладке «Обзор».

Закрыт

Все комментарии будут скрыты.

Забаненные пользователи

На вкладке Забаненные пользователи модераторы могут искать заблокированных пользователей. Если новый комментарий публикуется от забаненного пользователя, этот комментарий автоматически будет иметь ограниченную видимость и отображаться на вкладке «Обзор».

Настройки URL

Закрытие темы

Вы можете закрыть ветку комментариев по любому URL-адресу, где вы используете плагин комментариев. Это означает, что люди не смогут добавлять новые комментарии к обсуждению на этой веб-странице.