Комментирование: Недопустимое название — Викисловарь

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

Содержание раздела

Настройка

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

• Способ комментирования – выпадающий список, в котором можно выбрать варианты комментирования на сайте: встроенный, vk.com, facebook.com
• Пагинация – функция, позволяющая при большом количестве комментариев разбивать их на страницы. По умолчанию в настройках будет стоять значение (20), это поле будет редактируемым и пользователь сможет сам указать количество записей на странице.
• Доступ для роли – поле для выбора ролей пользователей, которым будет доступно комментирование на сайте. По умолчанию здесь установлена роль «Зарегистрированный».
• Идентификатор приложения VK – поле для ввода id приложения. Данное поле обязательно для заполнения при подключенном способе комментирования «vk.com». Для vk.com достаточно перейти на страницу.
• Идентификатор приложения Facebook – при выборе способа комментирования страниц сайта в фейсбуке достаточно выполнить следующие действия: перейти на страницу https://developers.facebook.com/apps и зарегистрироваться как разработчик, затем выбрать пункт «Создать новое приложение» и ввести нужные данные о сайте. На странице появится значение App ID: XXXXXX, где XXXXXX – id приложения. После этого нужно получить id пользователя, для этого можно следовать следующей инструкции.
• Включить комментирование для всех страниц – данная функция позволяет подключить возможность комментирования всех страниц сайта одним нажатием кнопки.
• Отправлять комментарии на e-mail – на электронный адрес модератора будет приходить сообщение следующего вида: Название страницы (title), на которой был размещен комментарий, затем текст комментария и гиперссылки: Открыть страницу, Удалить, Ответить.

Открыть страницу – открывается страница, на которой был оставлен данный комментарий;

Удалить – данный комментарий будет удаляться;

Ответить – открывается окно для ввода ответа на сайте на данный комментарий.

• Отправлять комментарии в задачу – Подключение этого пункта будет означать, что по умолчанию комментарии отправляются в задачу. Эта задача создается при создании первого комментария на сайте или по нажатию кнопки «Создать», справа в поле создания задачи в древовидной формы. По умолчанию задача назначается создателю сайта. В комментариях будет отображаться его содержимое и ссылки: Открыть страницу, Удалить, Ответить:

Открыть страницу – открывается страница, на которой был оставлен данный комментарий

Удалить – данный комментарий будет удаляться.

Ответить – будет открываться окно для ввода ответа на сайте на данный комментарий.

• Защитный код – возможность подключения возможности ввода защитного кода в форме комментирования перед отправкой комментария. Это позволит исключить попадания на сайт спам-рассылок, осуществляемых компьютерными ботами.

На панели управления страницей в правой части редактора CMS, в разделе «Дополнительные свойства» расположены функции:

«Разрешить комментирование» – функция позволяет подключать комментирование к отдельным страницам сайта. Когда она включена, внизу данной страницы в браузере появляется форма комментирования и лента комментариев.

«Комментировать вложенные» – функция доступна только на уровне разделов сайта и не распространяется на сам раздел. Т.е. в этом случает подключается комментирование вложенных страниц, а для страницы раздела комментирование определяется настройкой функции «Разрешить комментирование», описанной выше.

Как это работает на сайте

При подключенной функции«Отправлять комментарии в задачу» создается задача «Комментарии», вложенная в задачу с сайтом. В данную задачу будут поступать сообщения. Создание задачи сопровождается оповещением.

Чтобы оставить комментарий, достаточно в блоке «Комментировать» вписать комментарий, защитный код и нажать «Отправить».

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

При большом количестве комментариев в ленте (по умолчанию их количество должно быть больше 20) появляется пагинация.

Возле текста комментария (справа внизу) расположена кнопка «Ответить». При нажатии на нее пользователь может ответить на комментарий, оставленный другим пользователем.

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

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

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

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

Модерация

В свойствах сайта в разделе «Комментирование страниц» имеется возможность настроить модерацию с помощью пункта «Использовать предмодерацию».

• Использовать предмодерацию – выбор данного пункта позволит модератору сайта просматривать комментарии, оставленные пользователями, прежде чем они попадут на страницу. По умолчанию сообщения будут попадать сразу в задачу «Комментарии», в которой модератор сможет либо удалить это сообщение или подтвердить добавление этого комментария в ленту. Таким образом, можно избежать попадания на сайт спама, флуда, оскорблений и т. д.

При отправке комментария на сайте появляется оповещение «Комментарий отправлен на модерацию».

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

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

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

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

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

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

Хорошие против плохих комментариев

Как бы ни были важны комментарии, все еще можно писать плохие комментарии. Они всегда должны быть короткими, прямолинейными и добавлять информативную ценность.

Например, это довольно бесполезный комментарий:

b = 56                       # assigning b a value of 56  

Следующий пример демонстрирует более полезный комментарий и дает переменным очевидные имена:

salestax10 = 1.10            # defining a sales tax of 10%  
salestax20 = 1.20            # defining a sales tax of 20%  

Существует бесконечное количество других сценариев, которые заслуживают комментариев. Это только один пример. Хорошее практическое правило — добавлять комментарии к любой строке кода (например, к списку) или к фрагменту кода, цель которого не очевидна. Это очень субъективно, и на самом деле это навык, который необходимо изучить.

Типы комментариев

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

В следующих разделах я опишу каждый тип комментария.

Однострочные комментарии

Такой комментарий начинается с хеш-символа ( #) и сопровождается текстом, который содержит дополнительные пояснения.

# defining the post code
postCode = 75000  

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

# define the general structure of the product with default values
product = {  
   "productId": 0,          # product reference id, default: 0
   "description": "",       # item description, default: empty
   "categoryId": 0,         # item category, default: 0
   "price": 0.00            # price, default: 0.00
}

Руководство по стилю для кода Python ( PEP8 ) рекомендует менее 79 символов на строку. На практике 70 или 72 символа в строке легче читать, и поэтому рекомендуется. Если ваш комментарий приближается к этой длине или превышает ее, тогда вы захотите распределить его по нескольким строкам.

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

Как уже упоминалось выше, весь блок комментариев также понимается Python. Эти комментарии служат встроенной документацией для других, читающих ваш код, и обычно объясняют вещи более подробно

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

Версия 1 объединяет однострочные комментарии следующим образом:

# LinuxThingy version 1.6.5
#
# Parameters:
#
# -t (--text): show the text interface
# -h (--help): display this help

Версия 2 проще, чем версия 1. Изначально она предназначалась для создания документации (подробнее об этом ниже), но ее также можно использовать для многострочных комментариев.

"""
LinuxThingy version 1.6.5

Parameters:

-t (--text): show the text interface
-h (--help): display this help
"""
 

Обратите внимание, что последняя версия должна быть заключена в специальные кавычки ( """) для работы, а не хеш-символы.

Обычная практика

Довольно часто начинать Python-файл с нескольких строк комментариев. В этих строках указывается информация о проекте, назначении файла, программисте, который его разработал или работал над ним, и лицензии на программное обеспечение, которое используется для кода.

Этот фрагмент взят из одного из примеров, которые я использую в учебных целях. Комментарий начинается с описания, за ним следует уведомление об авторских правах с моим именем и год публикации кода. Ниже вы увидите, что код лицензирован под GNU Public License ( GPL ). Для того, чтобы связаться со мной, мой адрес электронной почты также добавлен туда.

# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
#
# (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email frank. [email protected]
# -----------------------------------------------------------

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

Python имеет встроенную концепцию под названием «строки документации», которая является отличным способом связать написанную вами документацию с модулями, функциями, классами и методами Python. Строка документа добавляется в качестве комментария прямо под заголовком функции, модуля или объекта и описывает действия функции, модуля или объекта. Ожидается, что будут следовать этим правилам:

Строка документа — это либо однострочный, либо многострочный комментарий. В последнем случае первая строка является кратким описанием, а после первой строки следует пустая строка.

Начните строку документа с заглавной буквы и завершите ее точкой.

Это основной пример того, как это выглядит:

def add(value1, value2):  
   """Calculate the sum of value1 and value2."""
   return value1 + value2

В интерактивной справочной системе Python строка документации становится доступной через атрибут __doc__.

>>> print add.__doc__
Calculate the sum of value1 and value2.  

Существует ряд инструментов, которые автоматически генерируют документацию из строк документации, таких как Doxygen, PyDoc, pdoc и расширение autodoc для Sphinx. Мы объясним вам, как работать с ними в следующей статье.

Заключение

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

Перевод статьи: Commenting Python Code

Комментирование кода и генерация документации в 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/ указывает на путь к файлам, которые вы хотите обработать.

Комментирование php кода, генерация документации. Горячие клавиши (комбинация) для комментирования кода

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

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

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

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

 

Плюсы и минусы комментирования кода

Процедура комментирования кода имеет как свои достоинства, так и недостатки.

Так, среди достоинств можно выделить:

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

К недостаткам можно отнести:

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

Примеры комментирования php кода

Для примера мы решили опубликовать некоторые выдержки из наших внутренних регламентов в части программирования на базе Framework Yii, что является наиболее актуальным в рамках ООП (объектно-ориентированного программирования).

По сути, саму структуру комментария можно наглядно представить как:

 

1. Класс

1.1. Константа

1.2. Свойство

1.3. Метод

 

В ходе описания класса рекомендуем комментировать виртуальные свойства класса, которые должны начинаться символом «@» с обязательным добавлением слова «property», что существенно облегчает процедуру написания кода на базе PHP в случае использования IDE PHPStorm. Практический пример таких описаний наглядно представлен ниже:

 

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

 

В свою очередь описание Свойства производится посредством определения типа данных с использованием команды «@var», что представлено ниже:

 

Статические свойства могут быть описаны следующим образом:

 

Описание методов модели производится посредством использования таких команд как:

• tableName(),
• rules(),
• attributeLabels(),
• behaviors(),
• beforeSave(), afterSave(),
• beforeFind(), afterFind(),
• beforeDelete(), afterDelete.

Пример описания методов моделей приведен ниже:

 

Отметим, что методы могут содержать комментарии «родительского» класса, что характеризуется параметром @inheritdoc.

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

 

На принтскрине выше пример, который говорит о том, что у метода уже есть комментарий (читай комментарий родительского метода).

Что такое комментирование для менеджера проекта

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

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

1. Предположим, что у нас имеется сайт с разделом, в котором представлена матрица изображений.
2. Отметим, что каждому типу пользователей присвоена собственная «роль» и свой уровень доступа. Среди таких ролей можно выделить: Гостей, Администратора сайта, Юридические и Физические лица и т.д.
3. Таким образом, каждое из представленных изображений в этой матрице может быть доступно или не доступно различным пользователям в зависимости от присвоенной им роли:

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

Класс — описательная часть бизнес-логики. Например, это часть, которая описывает:

— как загрузить объект;

— какие свойства и действия могут быть присвоены этому объекту;

— какие данные и где должны храниться;

— информацию о валидации данных.

1. Константа — не меняющаяся величина. В нашем примере это может быть конкретный путь к директории, где хранятся картинки.
2. Свойство — переменные в классе. Если бы у нас на странице была форма обратной связи, то это были бы поля, которые должен заполнять пользователь.
3. Метод — действия над объектами. Например, процедура загрузки картинки для нашей матрицы.

Горячие клавиши для комментирования кода

Любое написание кода и составление комментариев — это время, а, следовательно,  и материальные затраты. Мы настоятельно рекомендуем вам использовать горячие клавиши с тем, чтобы экономить время.

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

Среди таких «горячих» клавиш следует выделить:

 

Ctrl+Alt+L — выстраивается структура кода;

 

Ctrl+Alt+J — обернуть тег в другой тег, удобно при вёрстке;

 

Двойное нажатие на клавишу Shift — глобальный поиск;

 

Ctrl+Shift+F — поиск в каталоге по всем файлам этого каталога;

 

Ctrl+Shift+R — быстрая замена текста в файлах выбранного каталога;

 

Alt+Insert —  при нахождении в теле необходимого класса можно генерировать геттеры и сеттеры, или перераспределять родительские методы и свойства.

 

Генерация документации на основании комментариев в коде

Многие заказчики часто просят документацию к проекту при этом сами не сознают где и как они будут ей пользоваться.

Мы давно уже перестали создавать большие ГОСТовские документы, которые сложно актуализировать и не понятно, как применить.

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

1. Техническое задание, которое описывает бизнес-логику разрабатываемого программного решения.
2. Сгенерированная документация для разработчиков на основании оставленных комментариев в коде.

 

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

1. В качестве примера будем использовать расширение «yii2-apidoc» для фреймворка yii2 (если пишите на другом фреймворке, то есть масса аналогов, например ApiGen, или phpDocumentor.
2. После установки расширения через консоль выполнить команду, которая сформирует документацию в html-формате.

 

 

Сформированная документация будет являться удобным инструментом для разработчиков: появится возможность быстрого поиска (встроенного в страницу) и  возможности проваливаться во вложенные элементы документа. То есть, это полноценный сайт, который составлен на основании комментариев в коде.

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

 

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

Комментаторская активность в Живом Журнале (ЖЖ) чаще сосредоточена вокруг топовых блогеров. Авторство постов играет большую роль в образовании дискуссий, чем тематика. К таким выводам в ходе исследования пришли ученые из Лаборатории интернет-исследований (ЛИНИС, Санкт-Петербург) НИУ ВШЭ Олеся Кольцова, Сергей Кольцов и Сергей Николенко

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

Олеся Кольцова, Сергей Кольцов и Сергей Николенко предположили, что сходные по тематике посты должны привлекать примерно одних и тех же комментаторов. Если человек интересуется, например, кулинарными рецептами, он может комментировать все или многие посты по этой теме, и так же будут делать другие заинтересованные пользователи. Таким образом, вокруг постов с рецептами должно образовываться облако комментариев от одних и тех же лиц. Если же облако нарастает вокруг постов одного автора, а не одной темы, можно говорить о том, что эти авторы – лидеры мнений для данного круга комментаторов-поклонников.

Пытаясь проверить это предположение, исследователи обратились к материалам Живого журнала. Именно ЖЖ был выбран в качестве объекта исследования, поскольку в России до недавнего времени большая часть социально-политических дискуссий была сосредоточена в рамках этого ресурса.

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

В выборку вошли все посты двух тысяч самых популярных блогеров ЖЖ, написанные в течение недельного периода. Именно в диапазоне верхних двух тысяч блогов комментариев достаточно для образования «облаков» или сообществ, отмечают авторы в докладе, посвященном результатам исследования. «Эксперименты с рейтингами показали, что уже на уровне 50-тысячного места количество комментариев почти вдвое меньше количества постов и составляет менее трех комментариев на блогера, – пишут исследователи. – Если учесть, что эти блогеры – уже не знаменитости, вероятность комментирования разных постов одним и тем же пользователем крайне мала».

Также из всех предыдущих исследований лаборатории известно, что на топ-2000 блогеров (примерно 1% от всех аккаунтов) приходится почти в двадцать раз больше комментариев, чем постов, и здесь в выборку попадают активные комментаторы, оставляющие множество комментариев, отметили ученые.

Выбор недельного периода для анализа (с 1 по 7 апреля 2013 года) авторы объясняют тем, что большинство комментариев к посту обычно появляется в течение нескольких дней. После исключения постов, не имеющих комментариев, в исследовательском фокусе внимания оказалось 17386 постов, написанных 1667 авторами. Количество комментариев к ним составило 520 тысяч. Они были оставлены примерно 56 тысячами блогеров.

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

Первично авторство, а не тема

Анализ показал, что большое количество (85) мелких сообществ – это диады и триады, зачастую изолированные и не представляющие содержательного интереса. Это, по словам авторов, одно из последствий неравномерного распределения числа комментариев на пост и особенно числа комментариев на комментатора. Около трети комментаторов в выборке оставили всего по одному комментарию и, таким образом, вообще не участвуют в графе со-комментирования. Остальная группа сформирована по большей части менее чем тысячей активных комментаторов, сгенерировавших от ста до примерно тысячи комментариев каждый. На эту группу приходится две трети всех комментариев. Самое большое сообщество не представляет существенного интереса так же, как и самые маленькие. Это «разговор всех обо всем». Потенциально интересными оказались около семидесяти средних сообществ.

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

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

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

См. также:

Топовые блогеры мало отличаются от обычных
Блогосфера демонстрирует живучесть
Политическая активность в соцсетях подвергается манипуляциям
Facebook и Вконтакте мешают друг другу
Facebook и ТВ, революция и контрреволюция

 

---

Подпишись на IQ.HSE

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

Комментирование кода —  это внесение пояснений в тест модулей, которые не является обязательными и не влияют на алгоритм (не исполняются)

Производится только с помощью последовательности «//«, при этом комментарием считается все, что находится после.

Пример комментария:

Перем ЭтоНеКомментарий;\\ А это уже комментарий \\Это тоже комментарий

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

Возможно использование в подряд идущих комментариев:

//Это первая строка комментария
//Это вторая строка комментария

//Строка комментария после пустой строки 
// Перем А;//Эта переменная не объявится

Горячие клавиши

ctrl + / — добавить комментарий в выделенных строках;

ctrl + shift + / — удалить комментарий в выделенных строках

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

Установка и снятие комментария интерактивно по кнопкам:

Выделяется код и нажимаются на панели «Модуль» соответствующие кнопки «Добавить комментарий» и снять «Комментарий»

 

или более длинный путь:

Меню «Текст\Блок\Добавить комментарий» или «Текст\Блок\Удалить комментарий«

 

Должен заметить, что текст комментариев —  только для программистов, пользователь его не увидит, и служит для:

• описания сложных участков кода или алгоритма
• логического отделения блоков непрерывного кода, в данном случае поле «\\» ничего не пишется
• описания функций и процедур
• выделения изменений в код типовых конфигураций, при обновлении упростит разбор
• описания ситуации внесения изменений, даты
• отметка ошибочного или сомнительного кода, в процесcе code review (анализа  качества кода 1С)

Правила комментирования кода действуют и для языка запросов 1С, но важно отметить, что  при использовании Конструктора запроса(визуального средства разработки запроса к базе), комментарии удаляются полностью, а не снимается признак «\\».

Среда разработки может автоматически сворачивать комментарии, для удобства восприятия

Настроить это можно в меню «Сервис\Параметры» далее вкладки «Модули\Группировка»

Там же на вкладке «Модули\Редактирование» возможно отключить или поменять цвет выделения комментария с зеленого (по умолчанию)

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

 

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

— Джон Кеннет Гэлбрейт

Комментирование в Фигме | Бложик о дизайне

Скажи, в начале работы с новым заказчиком ты сейчас оговариваешь, в чем для него лучше делать дизайн (Фигма / Фотошоп)?

Нет. В конце даю ссылку на видос

и все. Месяца 3 назад был 1 случай, когда и так с заказчиком не очень понимали друг друга — ну это вот такие заказчики, которых ты в конце проекта не очень ждешь на веблансере, чтобы они отзыв оставляли, потому что хрен его знает, что они там тебе напишут — вот тоже было: «нужен фотошоп!!!!» / «ВЕРСТААААЛЬЩИКИ СКААААЗАЛ НУЖЕН ФОТОШОООООП!!!» / «у тебя на сайте нигде не написано, что ты делаешь макеты в какой-то фигме!!!!». На что естественно, я в ответ ответил, что и в ТЗ не было ни слова про Фотошоп, иначе я бы отказался. Короче как два барана матом орали друг на друга минут 20 и соревновались в количестве восклицательных знаков. Потом надоело, сказал ему, чтобы успокоился и просто видос мой глянул. Ну и показал ему некоторые фишки, вроде расшаренного экрана, комментирования, истории версий. Через 10 минут согласился, что фигма сильно лучше и извиняться начал. Но такое было 1 раз, поэтому не вижу повода переживать 🙂

Делая проект в Фигме, ты выносишь что-то на отдельные страницы

Нет, все делаю на соседних фреймах. У меня, к слову, в библиотеке компонентов только курсор-палец, который я ставлю, чтобы показать ховеры 🙂 Сильно быстрее, нарисовать кнопку с нуля (это же просто прямоугольник и текст), и сделать из нее компонент, чем лазить в библиотеку, там что-то искать, потом переносить в макет, переключать вкладку обратно, компонент перетягивать по слоям в нужное место. Причем все равно прямоугольник придется перенастраивать и текст перепечатывать. Надо работать так, чтобы время экономить, а не тратить. Вот примерно из этой серии и дополнительная страница со всякой «хренью» 🙂 Которую еще не факт, что верстальщик найдет потом))

По умным направляющим от высоты текстового блока?

Да. И на вертикальный ритм, на который мастурбирует каждый второй, мне вообще по барабану. Практически никогда ничего по нему не выравниваю. Вернее не перепроверяю попало ли у меня в вертикальный ритм или нет.

Вставить или удалить комментарий

Добавление комментариев к определенным частям документа делает ваш отзыв более понятным. Если кто-то еще комментирует документ, ответ на его комментарии позволит вам обсудить его, даже если вы не все присутствуете в документе одновременно.

1. Выберите контент, который хотите прокомментировать.

2. Перейти к обзору > Новый комментарий .

3. Введите свой комментарий. Если вы хотите внести изменения в какие-либо свои комментарии, просто вернитесь и отредактируйте их.

4. Чтобы ответить на комментарий, перейдите к комментарию и выберите Ответить.

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

Удалить комментарии

Щелкните комментарий правой кнопкой мыши и выберите Удалить комментарий.

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

1. Выберите контент, который хотите прокомментировать.

2. Выберите Просмотр > Новый комментарий .

3. Введите свой комментарий и выберите Опубликовать .

4. Чтобы ответить на ветку комментариев, перейдите к комментарию и выберите @mention или ответить .Взаимодействие с другими людьми

Пузыри на полях укажите, где кто-то оставил комментарий.

Практикуйтесь с комментариями и другими функциями совместной работы в Word, загрузив это учебное пособие «Совместная работа в Word».

Редактировать комментарии

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

Примечание. В Word для Интернета мы ограничили доступ к параметру «Редактировать комментарий» только для комментариев, созданных вами. Однако имейте в виду, что другие пользователи по-прежнему могут редактировать ваши комментарии, напрямую изменяя ваш файл Office.

Удалить комментарии

Вы можете удалить комментарий, выбрав Удалить цепочку в раскрывающемся меню «Дополнительные действия цепочки», которое находится в правом верхнем углу комментария.

Как увеличить количество спонтанных комментариев ваших учеников с РАС

Поделиться — это забота!

История успеха Сэма

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

Дилемма Данте и Бонни

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

Бонни больше комментирует то, что ей нравится, но часто это принимает форму следующего:

• Бонни просит любимую еду.
• Учитель дает Бонни ее любимую еду.
• Бонни пробует его на вкус и говорит «Ням», используя свое устройство для генерации речи.

Но Бонни ничего не говорит о других продуктах, которые она ест. Кроме того, она каждый раз делает один и тот же комментарий, а не создает спонтанный комментарий о новых ситуациях.

Почему это так сложно?

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

Это отличные места для начала, но, конечно, мы всегда хотим, чтобы наши студенты делали больше. Итак, что делать дальше? Получить спонтанные комментарии действительно сложно. Это требует, чтобы учащиеся были мотивированы к взаимодействию в социальных целях и чтобы мы могли успешно устранять наши реплики или подсказки (как я уже говорил, говоря о полосах предложений). Это также требует от учеников выработки языка, соответствующего ситуации, что может быть непросто.

Что мы можем сделать?

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

1. Просмотрите расписание занятий и выделите для ученика 2 задания, в которых вы можете создать как минимум 5 возможностей для ученика что-то прокомментировать. Если вы не можете дойти до 5, ничего страшного. Как только вы начнете, вы можете найти больше. Включите их в свой план педагогического вмешательства, чтобы все работали над ними.Поместите их в свой натуралистический лист данных, чтобы напомнить персоналу о необходимости их решения. Когда они освоят 2 действия, поставьте цель еще на 2.
2. Сделайте визуальные подсказки для персонала, чтобы все не забыли воспользоваться возможностью подождать, пока студент сделает комментарий.
3. Имейте коммуникационную поддержку в каждом занятии дня, чтобы поддержать комментирование различных аспектов занятия. Таким образом, если представится возможность, опоры будут на месте.
4. Измените типы подсказок, которые вы используете для поощрения комментирования, чтобы учащиеся не запутались.Наши ученики склонны следовать распорядку, поэтому чем больше мы его встряхиваем, тем выше вероятность, что у вас возникнет спонтанность.
5. Наконец-то подкрепите чертовски спонтанные комментарии, когда они случаются. Сделайте спонтанные комментарии там, где их никто не настраивал и не подсказывал, чтобы они стали самым важным навыком. Увеличьте количество подкреплений или фактор возбуждения, чтобы отличить их от комментариев при получении сигнала.

Комментирующие карточки

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

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

1. Мы решили, что она каждый день гуляет с обычным сверстником по школе. Мы организовали 4 или 5 регулярных остановок возле школы, о которых они могли бы поговорить. Иногда добавляли специальные, если что-то добавляли. Остановки включали доски объявлений, аквариум в классе, художественные выставки в коридоре, окно с видом на детскую площадку или другие окна и тому подобное.
2. На каждой остановке во время прогулки сверстник делал комментарий об обозначенном предмете. Он / она может прокомментировать, что делала рыба.Затем они предлагали ученику взглянуть на карточку с комментариями. Карточки с комментариями, как вы можете видеть ниже, не были конкретными вещами. Это была скорее карта предложений того, что она могла сказать.
3. Таким образом, у ученика было 5 возможностей прокомментировать различные вещи в школе и поддержку, а также образец от сверстника.

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

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

Загляните в это воскресенье, чтобы узнать интересные новости и идеи! До следующего раза,

Комментируя ваши СМИ | Поддержка Frame.io

Основная цель цикла проверки и утверждения — предоставить обратную связь посредством комментариев и сотрудничества с вашей командой.

Комментарии

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

Введите @, чтобы указать конкретного члена команды или сотрудника. Упоминание члена команды, который еще не добавлен в проект, в качестве соавтора автоматически добавит его за вас. Узнайте больше о добавлении членов команды в проекты здесь 👍

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

Push-уведомления будут отправляться пользователям во фрейме.io iOS app 📱

Чтобы отправить свой комментарий, нажмите Отправить или нажмите клавишу Enter , после отправки клип возобновит воспроизведение.

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

Комментарии на основе диапазона

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

💡 Shortcut Pro Tip : Удерживая нажатой клавишу Shift, используйте стрелки влево / вправо для точной чистки.

Нажмите клавишу ESC, чтобы удалить диапазон, если вы предпочитаете оставить комментарий с меткой времени.

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

Нажмите клавишу ESC, чтобы очистить диапазон / петлю воспроизведения.

💡 Shortcut Pro Tip: Удерживайте кнопку (R), чтобы вставить InPoint, после того как вы отпустите (R), ваша OutPoint будет установлена.

ПРИМЕЧАНИЕ: Аннотации будут отображаться в первом кадре диапазона.

Комментарии на основе диапазона входят в нашу интеграцию в Premiere и FCPX точно так же, как стандартные комментарии.

Комментарии только команды

Комментарии только команды похожи на личные / внутренние заметки, которые видны только другим членам команды в учетной записи.

Только члены команды могут оставлять только комментарии команды; соавторы и рецензенты не увидят эти внутренние комментарии.

Комментарии только для команды будут отображаться в золотом оттенке со значком замка 🔒

Члены группы также могут фильтровать типы комментариев в меню порядка сортировки комментариев, что означает, что у вас также есть выбор включения или исключения комментариев только команды при загрузке комментариев в виде TXT, CSV или XML.

ПРИМЕЧАНИЕ: Только для группы Комментарии доступны только для планов «Группа» и «Корпоративный».

Аннотации

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

Следующие статьи

Рекомендации по шаблонам комментариев — база знаний службы поддержки ISO

В этой статье

Лучшие практики

Неподдерживаемое форматирование

Шаблон комментирования в деталях

Проверка файла комментариев

Эта статья актуальна для:

Избиратель

Обратите внимание

• Менеджер комитета (CM), менеджер двойного комитета (Twinned CM), группа поддержки менеджера комитета (CM Support Team). Роли относятся только к техническим комитетам и их подкомитетам.
• Секретарь, Двойной секретарь, Секретарь / Руководитель группы поддержки. Роли группы поддержки относятся к рабочим группам (РГ), комитетам по политике и комитетам по управлению.

Шаблон комментариев ISO используется избирателями и комментаторами в процессе голосования для представления своих комментариев и замечаний руководителям комитетов ISO, секретарям ПК, а также организаторам и секретарям рабочих групп.

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

Избиратели и комментаторы должны всегда использовать последнюю версию шаблона комментариев для представления своих комментариев. Шаблон комментариев не следует изменять каким-либо образом (например, путем удаления / добавления столбцов, объединения ячеек и т. Д.).

Статьи по теме

Для получения дополнительной информации о том, как загрузить последнюю версию шаблона комментариев ISO , обратитесь к статье Cast Vote (см. Ссылку на статью внизу этой страницы)

• Обязательно используйте расширение файла комментария в нижнем регистре (в формате.doc или .docx)

• Введите только 1 комментарий в строке

• Заполните по крайней мере все обязательные поля ( MB , пункт , Тип комментария , Комментарий ) для каждой строки комментария

• Используйте клавишу Tab для перехода из одной ячейки в другую

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

• Избегайте добавления лишних символов Tab в конце документа (после таблицы)

• Не изменять ли макет шаблона (например, добавлять или удалять столбцы)

• Разве не разбивает таблицу комментариев на несколько таблиц

• Не изменять ли ширину отдельных ячеек

• Разве не объединяет ячейки (по вертикали и по горизонтали). Вместо этого обратитесь к другому комментарию или продублируйте текст
  

• Не добавлять ли текст, изображения и т. Д. Вне таблицы (до или после)

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

• Не вставлять ли таблицу в ячейку (тот же комментарий, что и в предыдущем пункте)

• Не использовать поля автоматической нумерации ( «серые» поля ).Вместо этого введите обычный текст

• Сделать без защиты паролем или защиты от записи ваш документ

Тело шаблона

В теле шаблона комментариев ISO вы вводите свои комментарии и наблюдения. Поля в таблице ниже, отмеченные звездочкой (*), являются обязательными, и необходимо заполнить для каждой строки комментария в шаблоне .

Поле	Описание
МБ / NC *	Указывает, кто отправил комментарий: — Члены ISO используют двухбуквенный код страны для своей страны — Связанные организации используют свое сокращение — Комитеты по связи используют свой номер комитета Комментарии ISO / CS отмечены двойной звездочкой « ** »
Номер строки	Укажите номер строки, к которой относится ваш комментарий.Нумерация строк редко отображается в документах ISO и поэтому не используется для сортировки комментариев.
Пункт / подпункт *	Укажите пункт / подпункт, к которому относится ваш комментарий. Для числовых пунктов введите только номер (а) пункта без каких-либо дополнительных формулировок. Если комментарий относится к более чем одному предложению, разделите предложения переносом строки (как показано ниже). Для нечисловых предложений используйте: — Общие для комментариев, относящихся ко всему документу — Введение для комментариев к разделу «Введение» — Приложение X.Y за комментарии к приложениям X.1, X.2 и т. Д. — пр.
Абзац / Рисунок / Таблица	Укажите абзац (внутри предложения), рисунок или таблицу, к которым относится ваш комментарий.
Тип комментария *	Выберите наиболее подходящий тип комментария для своего комментария: — ge : общий комментарий — te : технический комментарий — ed : редакционный комментарий
Комментарий *	Введите свой комментарий в этот столбец и объясните его причину.Вставляйте сложные объекты (таблицы, рисунки, изображения большего размера) как отдельные файлы в этот столбец или в столбец Предлагаемое изменение .
Предлагаемое изменение	Введите предлагаемые изменения.
Замечания секретариата	Оставьте этот столбец пустым . Используется Секретариатом для обозначения решения, принятого по каждому представленному комментарию.

Заголовок шаблона

Заголовок шаблона содержит основную информацию о комментируемом документе и / или проекте.

Пример файла комментариев

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

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

Уведомление, отправляемое пользователям, когда проверка файла комментариев не удалась

Избиратели и комментаторы, отправившие файл комментария с неподдерживаемым форматированным содержанием, получат следующее уведомление.

Комментирование коллекций | Центр обучения почтальонов

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

Содержание

Почтальон поддерживает комментарии к запросам и параметрам запросов.

Вы можете оставлять комментарии к коллекциям от Почтальона.

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

1. Войдите в Почтальон.
2. Вверху выберите Workspace , а затем щелкните вкладку Collections .
3. Откройте коллекцию, о которой хотите оставить свой комментарий, и нажмите Комментарии рядом с названием коллекции.

Вы можете комментировать запросы в Почтальоне. Вы можете публиковать комментарии только к сохраненным запросам.

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

1. Перейдите к запросу, к которому вы хотите оставить комментарий.
2. Переключитесь в режим Комментарий в правом верхнем углу окна.
3. Напишите свой комментарий, затем нажмите Добавить комментарий .

Вы можете оставлять комментарии к параметрам запроса (параметры запроса, параметры пути, заголовки, тела запроса типа form-data и x-www-form-urlencoded).

Вы можете добавлять комментарии только к сохраненным запросам.

1. Откройте запрос, который хотите прокомментировать.
2. Переключитесь в режим Комментарий в правом верхнем углу окна.
3. Щелкните ключ, значение или описание.
4. Введите свой комментарий, затем нажмите Добавить комментарий

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

1. Откройте запрос, который хотите прокомментировать.
2. Переключитесь в режим Комментарий в правом верхнем углу окна.
3. Откройте вкладку, на которой вы хотите оставить комментарий.
4. Выделите текст, который хотите прокомментировать.
5. Введите свой комментарий, затем нажмите Добавить комментарий

Вы можете видеть комментарии товарищей по команде к запросам и параметрам запросов в Postman.

Вы можете прочитать комментарии, сделанные к запросу и по параметрам запроса из приложения.

1. В Postman откройте запрос с комментариями, которые вы хотите просмотреть.

2. Переключитесь в режим Комментарий в правом верхнем углу окна.

   • Вы можете отфильтровать встроенные комментарии по Открытым комментариям , Решенным комментариям или по обоим.

Вы можете вносить изменения в уже размещенные вами комментарии. Другие члены команды не могут редактировать ваши комментарии.

1. В Postman откройте коллекцию с комментарием, который нужно отредактировать.
2. Найдите комментарий и щелкните Комментарий > Изменить .

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

1. Откройте коллекцию с комментариями, которые нужно разрешить.
2. Переключитесь в режим Комментарий в правом верхнем углу окна.
3. Нажмите Разрешить рядом с комментариями, которые нужно разрешить.

1. В Postman откройте коллекцию с комментарием, который вы хотите удалить.
2. Найдите комментарий и нажмите Комментарии > Удалить .

В целях модерации администраторы могут удалять комментарии, сделанные кем угодно, но не могут изменять комментарии.

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

1. В Postman откройте коллекцию или запрос, к которому вы хотите оставить свой комментарий.
2. Нажмите Комментарии и напишите свое сообщение.
3. Чтобы отметить своего товарища по команде, введите «@» и выберите его имя из списка.
4. Нажмите Добавить комментарий .

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

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

Следующие шаги

комментариев Postman поддерживают Markdown. Для получения дополнительной информации о форматировании с использованием Markdown см. Markdown в документации по API.

Комментирование записей и @ упоминание соавторов — Airtable Support

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

Комментарии отображаются в ленте активности записи после того, как запись была расширена.После расширения записи вы увидите комментарии к записи в ленте действий вместе с историей изменений на уровне записи. (Обратите внимание, что хотя ваша история изменений ограничена планом оплаты вашего рабочего пространства, комментарии останутся навсегда, пока не будут удалены вручную.)

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

В развернутой записи вы можете ввести комментарий в текстовом поле внизу ленты активности.

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

Когда вы @ упомянете соавтора, он получит уведомление о том, что вы упомянули его в данной записи. По мере того, как вы вводите свое сообщение в поле для комментариев, оно показывает, какие соавторы будут уведомлены, когда вы разместите свой комментарий. Чтобы разместить свой комментарий, нажмите клавишу Enter .

Обратите внимание, что если вы @ упомянули соавтора в комментарии, этот соавтор будет автоматически настроен на просмотр этой записи — это означает, что он будет уведомлен о дальнейших комментариях, которые вы сделаете к этой записи, даже если вы не @ упомянули их напрямую.

Вы также можете @ упомянуть соавтора в длинном текстовом поле. (Это также отправит уведомление @ упомянутому соавтору.)

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

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

Два коротких видеоурока, представленных ниже, могут дать вам дополнительную информацию о комментировании и @ упоминании соавторов:

Онлайн-комментирование — ONA EthicsONA Ethics

Просмотреть все темы

В этом разделе рассматриваются этические вопросы:

• Какова ваша цель предоставления онлайн-комментариев?
• Считаете ли вы это продолжением вашего новостного продукта?
• Какие правила вы должны ввести?

Новостным организациям не требуется размещать онлайн-комментарии, но ожидается, что в рамках своей журналистской ответственности они будут в той или иной форме высказывать мнение общественности.Фактически, в 1947 году Комиссия США по свободе прессы, также известная как Комиссия Хатчинса, заявила, что «форум для обмена комментариями и критикой» является одним из пяти требований «общество имеет право требовать от своей прессы. ”

В наше время общественность часто говорит в электронном виде, ставя лайки, делясь и комментируя. К сожалению для многих новостных организаций, комментирование превратилось в журналистский кошмар. Станут ли публичные комментарии тем, что The Washington Post называет «выгребной ямой», или общественным благом, о котором многие мечтали, когда онлайн-комментарии стали частью новостей в 1990-х?

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

Самое главное, считаете ли вы разделы комментариев частью вашего новостного продукта — регулируемыми правилами, которые вы применяете к вашей собственной журналистике, письмам редактору и колонкам мнений — или у вас будет отдельный стандарт для комментаторов? Чем больше вы считаете комментарии частью вашего новостного продукта, тем больше раздел комментариев должен отражать вашу журналистскую этику.

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

Но это не означает, что все редакторы и издатели запрещают их, согласно опросу Sounding Board, проведенному в 2014 году ассоциацией редакторов Associated Press Media. Было обнаружено, что 46 процентов из 101 участника опроса разрешили анонимные публикации.Тем не менее, большинство (54 процента) требовали от комментаторов называть себя, а 38 процентов требовали, чтобы комментаторы использовали свое имя и фамилию. Хорошо это или плохо, но некоторые считают, что запрет анонимной публикации значительно сокращает количество людей, которые будут оставлять комментарии.

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

Однако немногие организации допускают язык вражды и дискриминационные высказывания по признаку расы, этнической принадлежности, пола, сексуальной ориентации, экономического статуса, религии или культуры. Такие комментарии подрывают концепцию гражданского дискурса и снижают доверие общества к прессе, которое составляет 7 процентов, что является самым низким уровнем за всю историю (Центр исследований по связям с общественностью Associated Press-NORC, «Доверие к институтам: тенденции в отношении американцев к правительству»). , СМИ и бизнес »).

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

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

Но есть цена. В то время как активный модератор может помочь вашей новостной организации реализовать видение онлайн-комментариев, некоторые редакторы, участвовавшие в опросе APME, выразили обеспокоенность по поводу количества рабочего времени, необходимого для мониторинга.Круглосуточная модерация онлайн-комментариев была редкостью, и только 12 процентов редакторов сообщили о круглосуточном мониторинге персонала. Онлайн-комментарии модерировали сотрудники с 13 до 16 часов в день среди 27 процентов респондентов.

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

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

Именно потому, что онлайн-комментарии — это форум, который дает голос современной публике, они важны для будущего журналистики в демократическом обществе.