Здравствуйте, подкиньте пожалуйста материал или поделитесь личным опытом как правильно и грамотно комментировать свой код, с примерами. Тоесть название класса, его описание, описание его методов и т.д. С какой полнотой следует составлять комментарий к коду.
Всё, что поиск выдаёт - это какие виды комментариев бывают.
Полная Версия: Правильное комментирование
Код комментировать не нужно в большинстве случаев, я комментирую только типа параметров для методов и типы у свойств, а также вверху лицензию для своего проекта. Можно комментировать места где применяешь хак какой-нибудь.
_____________
Люди, имеющие низкий уровень квалификации, делают ошибочные выводы, принимают неудачные решения и при этом неспособны осознавать свои ошибки в силу низкого уровня своей квалификации
_____________
Люди, имеющие низкий уровень квалификации, делают ошибочные выводы, принимают неудачные решения и при этом неспособны осознавать свои ошибки в силу низкого уровня своей квалификации
| Цитата (ЗлОй ПрОграММер @ 22.05.2015 - 08:57) |
| название класса, его описание, описание его методов и т.д |
Можно посмотреть как РНР прокомментирован:
| Цитата (core.php) |
| /** * (PHP 4, PHP 5)<br/> * Get string length * @link http://php.net/manual/en/function.strlen.php * @param string $string <p> * The string being measured for length. * </p> * @return int The length of the <i>string</i> on success, * and 0 if the <i>string</i> is empty. */ function strlen ($string) {} |
Но также отмечу что такой комментарий вовсе и не комментарий как таковой, а описание функции которое затем отправляется в офф документацию. Это для того чтобы технический писатель не лазил по функциям, а брал вот такой вот комментарий и сочинял инструкцию к использованию функции. Еще можно обозначить названия тестов чтобы они автоматом создались в файле теста, но это нельзя назвать комментарием, а просто описание того какой тест применен к этой функции. Выполняется также как описание входных и возвращаемых значений.
Комментарии типа "тут в цикле вывожу значение переменной" не используются программистами, но используются обучающимися людьми чтобы потом не потеряться в коде. Те кто программировать умеет и так в коде не потеряется.
_____________
Трус не играет в хокей
| Цитата (chee @ 22.05.2015 - 11:02) |
| Код комментировать не нужно в большинстве случаев, я комментирую только типа параметров для методов и типы у свойств, а также вверху лицензию для своего проекта. |
плохие наставники у тебя были.
Нас в универе жестко били по рукам, если код был некоментирован.
А когда писали на ассемблере, так вообще некоментированный код не принимался к сдаче.
kaww
| Цитата |
| название класса, его описание, описание его методов и т.д |
Это не коентирование, это документирование.
Это необходимое, но не достаточное условие.
ЗлОй ПрОграММер
C опытом придет понимание минимально необходимого.
Не нужно через каждую строку ставить коментарии, иначе код будет просто невозможно читать.
Коментировать имеет смысл места, где разветвляется логика, особенно, если она не тривиальна и имеет множество ветвлений.
Так же, как уже заметил chee, если имеет место быть какая-нибудь нетривиальная операция/конструкция/блок (хак)
По большому счету ты коментируешь всего для 2х людей:
для себя через полгода и для того несчатного, который будет твой код после тебя разгребать.
Вот и делай это так, чтобы оба этих человека вспоминали тебя добрыми слованми и минимальным набором нецензурных слов
_____________
[продано копирайтерам]
всем спасибо
ЗлОй ПрОграММер, когда пишешь код, то представь, что кто-то его читает. И этот "кто-то" должен с ходу понять, что и почему тут сделано. Что-то будет понятно по коду, но не всё. Например, для чего нужны функции или константы, которые ты объявляешь. Что означают те или иные условия, особенно когда эти условия весьма навороченные. Ну и так далее.
_____________
* Хэлп по PHP
* Описалово по JavaScript
* Хэлп и СУБД для PostgreSQL
* Обучаю PHP, JS, вёрстке. Интерактивно и качественно. За разумные деньги.
* "накапливаю умение телепатии" (С) и "гуглю за ваш счет" (С)
_____________
* Хэлп по PHP
* Описалово по JavaScript
* Хэлп и СУБД для PostgreSQL
* Обучаю PHP, JS, вёрстке. Интерактивно и качественно. За разумные деньги.
* "накапливаю умение телепатии" (С) и "гуглю за ваш счет" (С)
sergeiss
меня больше интересовало, что нужно при комментировании скажем функции указывать, к примеру: входящие параметры функции, описание функции, что возвращает и т.д. и как это оформить правильно
За образец возьму пример который stump написал, например
правильно всё сделал?
и зачем @ используют при указании параметров?
меня больше интересовало, что нужно при комментировании скажем функции указывать, к примеру: входящие параметры функции, описание функции, что возвращает и т.д. и как это оформить правильно
За образец возьму пример который stump написал, например
/**
* Получает сумму двух переменных
* @param int $a
* @param int $b
* @return int сумму двух переменных
*/
function summ($a, $b) {
return int ($a + $b);
}
правильно всё сделал?
и зачем @ используют при указании параметров?
| Цитата (ЗлОй ПрОграММер @ 23.05.2015 - 00:58) |
| и зачем @ используют при указании параметров? |
Для того, чтобы некоторые проги могли автоматически брать данные и понимать, где тут параметры, а где возвращаемые данные.
И кстати. Я говорил не только про комментирование функций, но и про каменты в коде. Очень нужная фича
Проверено. Даже свой код открываешь через пару-тройку месяцев и не всегда помнишь, что означают те или иные условия, параметры, константы.
_____________
* Хэлп по PHP
* Описалово по JavaScript
* Хэлп и СУБД для PostgreSQL
* Обучаю PHP, JS, вёрстке. Интерактивно и качественно. За разумные деньги.
* "накапливаю умение телепатии" (С) и "гуглю за ваш счет" (С)
Здесь расположена полная версия этой страницы.