Как правильно комментировать PHP и JS-код, есть ли описанные где-то стандарты?

Question

[Роман]

Заказчик хочет чтобы разработка хорошо документировалась :)

Скажите, а есть ли какие-то формальные стандарты на этот счет?

Например, часто встречаешь в коде фреймворков что-то типа:

/**
     * Resolve the element's value.
     *
     * @param  mixed  $resource
     * @param  string|null  $attribute
     * @return void
     */

Такое где-то оговорено заранее? Какие-то спецификации может есть?

Спасибо.

Comments

[alex-1917]

Заказчик хочет чтобы разработка хорошо документировалась

Как правильно комментировать PHP и JS-код

Вы и правда не видите разницы?

Answer 1

[WapSter]

Для js пользуюсь данным методом, для php думаю он тоже подойдёт. Ну а так, код должен быть само документируемым, правильные названия переменных функций, в css БЭМ.

Answer 2

[abberati]

Нет, общего стандарта нет. Есть разные соглашения о формате комментариев. Например, jsdoc — это из вашего примера.

Answer 3

[Антон Р.]

При грамотно написанном ООП коде комментарии вообще не нужны )