Комментарии - одна из самых сложных тем в программировании. В каждом языке программирования существуют конструкции, не влияющие на ход программы и игнорируемые интерпретатором; почти каждое описание языка начинается с их указаний по их использованию (сразу после объявления синтаксиса, эти главы обычно пролистываются); и почти всякий программист хоть раз в жизни горько сожалел об отсутствии "этих бесполезных комментариев".
Комментарии - архинужная и архиважная вещь. Помимо прославления отдельного взятого author и установления его copyright на данный плод трудов, из правильно составленных комментариев обычно можно узнать о лицензии, месте данного кода в пакете, версии файла и пакета, дате, изменениях, содержании файла, используемых алгоритмах, процедурах, функциях, объектах, структуре файла и другие интересные вещи. Примеры см. в пакете pear.php.net.
Хотелось бы подчеркнуть, что комментарии никоим образом не заменяют и не подменяют необходимость документирования программного комплекса, общего хода работ и т.п.. Комментарии не являются заменой технической документации! При составлении техдокументации нельзя уповать на системы механического документирования (типа DoxyDoc), которые собирают подобие документации из комментариев в коде. Документирование - отдельный вид работ, который не рассматривается здесь, но, весьма вероятно, далее я напишу и об этом, и о ГОСТах на составление ТД, которые никто не отменял.
Вернёмся к сложности комментариев. Казалось бы, пока ничего сложного, написал что-нибудь эдакое:
// myfile.php, v.0.2, 2006, (c)me
и комментарий готов. Ан нет; комментарию, помимо свойства краткости, должно быть присуще свойство полноты, либо достаточности. Комментария должно быть достаточно для понимания другим равноквалифицированным специалистом исходящих данных об описываемом объекте. Например:
// myfile.php, v.0.2, main file of MyProject - part 0 - examples' Remark for comments, 2006, (c)me
Ещё одно свойство комментариев - отсутствие избыточности и тавтологии. Например, нет необходимости писать такой комментарий в подобной ситуации:
// Create Objects
function createObj( $objName )
Но, если б эта функция, например, была бы методом некоего класса, комментарий мог бы выглядеть так:
/**
Factory method, фабричный метод
@param $objName имя класса объекта, string
@return $ret ссылка на новый объект требуемого класса
*/
function & createObj( $objName )
{
$ret = & new $objName;
return $ret;
}
Пояснения: а) фабричный метод - один из паттернов проектирования (design pattern), здесь не рассматривается. См. соответсвующую литературу. б) Использован синтаксис PHP. в) Стиль комментариев: DoxyDoc, опции Java, C.
Из данного комментария мы можем почерпнуть информацию о целевом назначении метода, о принимаемых параметрах и возвращаемых значениях. И таким образом, не вдаваясь в детали реализации, положившись на профессональную честность автора в области обезбаживания собственного кода, можем использовать программный интерфейс для собственных нужд. (Если на то есть соответствующее разрешение, лицензия.)
Кстати, совсем не дурно было бы составлять комментарии не только на Вашем родном языке, но и на одном из "языков межнационального общения" принятых ООН, в соответствии с предполагаемым ареалом распространения Вашего кода. И очень хорошо, когда комментарий написан грамотно! Повторяю: грамотно.
Можно ли обойтись без комментариев, не писать их? Угадали, конечно можно! Некоторые авторы именно так и поступают. Я сам знаю лично несколько человек.
По поводу отсутствия комментариев существует несколько мнений. Если не принимать во внимание оскорбительные мнения типа "автор кода - лентяй", можно выделить три точки зрения:
1) либо автор - гений, и он способен держать в собственной памяти все назначения переменных, функций, именования объектов и его голова от этого не пухнет;
2) либо автор считает, что написанный им код настолько ясен и доступен для понимания, что нет необходимости его документировать и комментировать;
3) либо автор предполагает, что код не будет использоваться ещё где- и когда-либо, и просто решил сэкономаить время на писании комментариев.
Первый случай обычно можно узнать по конструкциям типа if(!isset($var) && $var===true), третий - по сваленному в кучу неформатированному коду, второй - когда Вы просматриваете файл и видите исходящий от кода свет, на Вас снисходит благодать и Вы чувствуете переход в godmode, и в каждой руке по бфг9000, и фулплейт, и уже нет небходимости жать IDDQAIDKFA...
Wake up!
Write comments!
// праснис! пешы каменты!
#####################
# (c)me, 2005-2006, 24-26.11.2006
# К вопросам этики и эстетики в программировании, часть 0
#
Комментарии - архинужная и архиважная вещь. Помимо прославления отдельного взятого author и установления его copyright на данный плод трудов, из правильно составленных комментариев обычно можно узнать о лицензии, месте данного кода в пакете, версии файла и пакета, дате, изменениях, содержании файла, используемых алгоритмах, процедурах, функциях, объектах, структуре файла и другие интересные вещи. Примеры см. в пакете pear.php.net.
Хотелось бы подчеркнуть, что комментарии никоим образом не заменяют и не подменяют необходимость документирования программного комплекса, общего хода работ и т.п.. Комментарии не являются заменой технической документации! При составлении техдокументации нельзя уповать на системы механического документирования (типа DoxyDoc), которые собирают подобие документации из комментариев в коде. Документирование - отдельный вид работ, который не рассматривается здесь, но, весьма вероятно, далее я напишу и об этом, и о ГОСТах на составление ТД, которые никто не отменял.
Вернёмся к сложности комментариев. Казалось бы, пока ничего сложного, написал что-нибудь эдакое:
// myfile.php, v.0.2, 2006, (c)me
и комментарий готов. Ан нет; комментарию, помимо свойства краткости, должно быть присуще свойство полноты, либо достаточности. Комментария должно быть достаточно для понимания другим равноквалифицированным специалистом исходящих данных об описываемом объекте. Например:
// myfile.php, v.0.2, main file of MyProject - part 0 - examples' Remark for comments, 2006, (c)me
Ещё одно свойство комментариев - отсутствие избыточности и тавтологии. Например, нет необходимости писать такой комментарий в подобной ситуации:
// Create Objects
function createObj( $objName )
Но, если б эта функция, например, была бы методом некоего класса, комментарий мог бы выглядеть так:
/**
Factory method, фабричный метод
@param $objName имя класса объекта, string
@return $ret ссылка на новый объект требуемого класса
*/
function & createObj( $objName )
{
$ret = & new $objName;
return $ret;
}
Пояснения: а) фабричный метод - один из паттернов проектирования (design pattern), здесь не рассматривается. См. соответсвующую литературу. б) Использован синтаксис PHP. в) Стиль комментариев: DoxyDoc, опции Java, C.
Из данного комментария мы можем почерпнуть информацию о целевом назначении метода, о принимаемых параметрах и возвращаемых значениях. И таким образом, не вдаваясь в детали реализации, положившись на профессональную честность автора в области обезбаживания собственного кода, можем использовать программный интерфейс для собственных нужд. (Если на то есть соответствующее разрешение, лицензия.)
Кстати, совсем не дурно было бы составлять комментарии не только на Вашем родном языке, но и на одном из "языков межнационального общения" принятых ООН, в соответствии с предполагаемым ареалом распространения Вашего кода. И очень хорошо, когда комментарий написан грамотно! Повторяю: грамотно.
Можно ли обойтись без комментариев, не писать их? Угадали, конечно можно! Некоторые авторы именно так и поступают. Я сам знаю лично несколько человек.
По поводу отсутствия комментариев существует несколько мнений. Если не принимать во внимание оскорбительные мнения типа "автор кода - лентяй", можно выделить три точки зрения:
1) либо автор - гений, и он способен держать в собственной памяти все назначения переменных, функций, именования объектов и его голова от этого не пухнет;
2) либо автор считает, что написанный им код настолько ясен и доступен для понимания, что нет необходимости его документировать и комментировать;
3) либо автор предполагает, что код не будет использоваться ещё где- и когда-либо, и просто решил сэкономаить время на писании комментариев.
Первый случай обычно можно узнать по конструкциям типа if(!isset($var) && $var===true), третий - по сваленному в кучу неформатированному коду, второй - когда Вы просматриваете файл и видите исходящий от кода свет, на Вас снисходит благодать и Вы чувствуете переход в godmode, и в каждой руке по бфг9000, и фулплейт, и уже нет небходимости жать IDDQAIDKFA...
Wake up!
Write comments!
// праснис! пешы каменты!
#####################
# (c)me, 2005-2006, 24-26.11.2006
# К вопросам этики и эстетики в программировании, часть 0
#
Сообщения
