Как правильно комментировать код?

Question

[Богдан Герасименко]

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

В частности интересует, когда писать

/*
 * Комментарий так
 */

а когда достаточно
// просто так.

Также видел, некоторые крупные разработки содержат в комментариях информацию о том, какие параметры принимает и возвращает функция.

Где можно почитать или узнать как правильно комментировать код?

Answer 1

[Antiless]

/** */ - PHPDoc
// - обычные коментарии

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

ps
при этом всем главное не забывать давать внятные имена переменным, методам, объектам и тд

Comments

[Богдан Герасименко]

PHPDOC это из разряда Enterprise разработки?

[Antiless]

Богдан Герасименко: из разряда адекватной разработки, не на один день

[Богдан Герасименко]

Antiless, спасибо, буду изучать что такое PHPDOC.

Answer 2

[Twelfth Doctor]

/*
 * Комментарий так
 */

Используется для больших комментариев, которые на одну строку не умещаются
А //такой комментарий - для небольших комментариев, занимающих одну строку

Answer 3

[Александр Шаповал]

Также видел, некоторые крупные разработки содержат в комментариях информацию о том, какие параметры принимает и возвращает функция.

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

function test(int $id, array $user): array
{
    return [];
}

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

Comments

[Богдан Герасименко]

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

[4iloveg]

Богдан Герасименко: Эти комментарии нужны для автокомплита в IDE в коде выше это для php7 у версий ниже желательно делать эти комменты.

[Алексей Николаев]

> array $data
Очень понятный параметр. Что должно быть в $data? Какие свойства?

[DevMan]

какие нафиг старые разработки?
потрудитесь узнать что такое докблоки и зачем их пишут.

[Сергей delphinpro]

Это не "устаревшие" разработки =))
Это phpdoc для автоматической генерации документации.

[Александр Шаповал]

Сергей: документация теперь может генерироваться на основе непосредственно передаваемых параметров с указанными типами =)

[Сергей delphinpro]

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

[Александр Шаповал]

Сергей: я имел в виду что не нужно комментировать типы передаваемых и возвращаемых значений, например:
function name(int $id): int
принимает и возвращает число

[Сергей delphinpro]

Александр Шаповал: Это я понял. Но тот же формат phpdoc подразумевает полное описание параметра
/** @param int $id identifier of user */
Можно опустить тип, но вы же не напишете только описание
/** identifier of user */
Как понять, к чему оно относится. Так что если речь идет о документировании, то всё пишется как и раньше, несмотря на новые плюшки в php7

[Александр Шаповал]

Сергей: не учел качество документирования, видел документации где описаны лишь типы данных, о такой документации сразу же и подумал)