комментарии (сопровождение программ)
Страница 1 из 1
комментарии (сопровождение программ)
Eric-S Вт Сен 23, 2008 8:26 pm
Для вставки описания кода, примечаний и пояснений, обычным текстом, на естественном языке используются комментарии.
простые (строчные) комментарии
В начале комментария нужно поставить символ апострофа "'".
После него, можно писать всё, что угодно, до конца строки.
Вот например
Не обязательно отводить под комментарий отдельную строку, можо это делать и в тойже строке, что и инструкции.
Компилятор пропускает комментарии. Они не влияют на готовую программу.
сложные (блочные) комментарии
Есть так называемые блочные или сложные комментарии. Они позаимствованы из языка C. Эти комментарии должны иметь явное начало "/'" и явный конец "'/". Причём перенос строки уже не играет роли. Вот например
или можно так,
Как видно из примеров, ничего сложного в них нету. Названы же они так только по аналогии с простыми. А раз есть простые и другие, то назвали их сложными.
как писать комментарии
Комментарии нужны только для сопровождения кода.
Многие люди придерживаются идеи о том, что хорошо написанная программа должна быть самодокументированной (не содержать комментариев, но, несмотря на это, легко читаться). К сожалению, в больших проектах этого добиться обычно не удается. Комментарии жизненно необходимы на всех этапах программирования, какдля вас, так и для остальных людей.
Если вы не писатель в душе, то ненавидите вставлять комментарии во время кодирования. В крайнем случае, откладываете это «на потом»: «Я вставлю комментарии после того, как программа заработает». Обычно это «потом» так и не настает, так что программа остается без комментариев, а значит, низкого качества (что бы там ни говорили, в большинстве случаев это так).
Про то, как желательно составлять комментарии, мы поговорим чуть ниже, а пока замечу одну деталь. Вы можете комментировать вашу программу, как вам вздумается. Но гораздо удобнее и приятнее будет придерживаться одного определенного стиля комментирования, как вы делаете это при написании кода. Четко выраженный стиль комментирования позволит также в перспективе создать программу, которая будет «шерстить» ваш код, выделяя из него комментарии и идентификаторы. Хороший пример этому — вставлять описания функций непосредственно перед ее заголовком. В дальнейшем с помощью автоматических утилит будет возможно выделить такие описания и даже создать на их основе нечто вроде документации.
Не думайте, что чем больше комментариев в программе, тем лучше.
Это утверждение прямо противоположно предыдущему, но никто и не говорил, что мы будем рассматривать только стереотипы из «одной корзины». Если вас иногда «заносит» и вы начинаете писать огромное количество комментариев в своем коде (а именно это частенько происходит со мной), если в вашей программе комментарии составляют более половины текста, время остановиться и задуматься. Налицо некоторая ошибка, но в чем же она заключается?..
И тут мы сталкиваемся с проблемой, у которой, вообще говоря, нет определенного решения. Можно лишь дать некоторые рекомендации и примеры того, когда следует писать комментарии, а когда — воздержаться, потому что и так очевидно, что делает программа. В этом смысле значительное преимущество имеют лица с раздвоением личности (я уже как-то писал, что эта особенность вредна для всего, чего угодно, но только не для программирования). Итак, написали пару строчек кода, — попробуйте взглянуть на них «свежим взглядом», как будто бы текст создали не вы, а кто-то еще. Если вам кажется, что код непонятен, то... Как вы думаете, что нужно сделать?..
Нет, не садиться комментировать на три страницы, ни в коем случае! Прежде всего, стоит подумать, нельзя ли участок программы написать получше. Возможно, это потребует перелопачивания некоторого объема кода выше и ниже только что вставленного фрагмента. В принципе, не стоит этого бояться: обычно любая реорганизация программы ведет к ее улучшению, а никак не к ухудшению (в крайнем случае, всегда можно вернуться к предыдущей архивной копии). К тому же, возможно, улучшение будет столь значительным, что в будущем вы скажете себе за него спасибо.
Предположим, вы все-таки решили вставить комментарий (естественно, это когда-нибудь произойдет). Что именно в нем написать?.. Не пытайтесь описать кусок кода изолированно: лучше опишите общими словами, что он делает, а также какие результаты будут получены после его выполнения. Вот пример неверного комментария:
' $elt хранит первый элемент списка.
my $elt=$obj->getFirst();
' Инициализируем нулем.
my $n=0;
' Пока текущий элемент существует...
while($elt) {
' Увеличить $n...
$n++;
# $elt = следующий элемент
$elt=$elt->getNext();
}Фактически, он может показаться верным с первого взгляда, но, тем не менее, тут допущена грубая ошибка, хуже которой — только вообще неработающий код.
Заметьте также, что комментарии составляют больше половины текста этой программы и загромождают ее. Если бы не выделение цветом, вообще трудно было бы разобрать, где код, а где примечания к нему.
Приведу теперь пример того, как можно откомментировать этот код. Наверняка мой вариант тоже не идеален, но он, по крайней мере, более информативен.
' $obj - список окон на рабочем столе.
' Считаем, сколько их.
my $elt=$obj->getFirst();
my $n=0;
while($elt) {
$n++;
$elt=$elt->getNext();
}
# Теперь $n - число окон.Наверное, вы поняли, что я сделал: просто убрал комментарии из мест, где и так все понятно. Перебирать связанный список можно
только одним способом — нет никакой необходимости это разъяснять. Зато нужно пояснить, что же в реальности хранится в той или иной переменной — ведь программист может случайно наткнуться на этот код, не глядя на всю его «предысторию».
Так как в этом примере читабельность кода между комментариями, в общем-то, не имеет особого значения, можно записать его короче и изящнее — вот так: # $obj - список окон на рабочем столе.
# Считаем, сколько их.
my $n=0;
for(my $e=$obj->first(); $e; $e=$e->next(), $n++) {}
# Теперь $n - число окон.
К моему большому сожалению, длинная строчка этого кода не влезала бы на страницу в браузере, если бы я не сократил имена методов до first() и next(). А
значит, пример произвел бы скорее негативное, чем положительное впечатление. Мне даже пришлось уменьшить шрифт, чтобы не появились линейки прокрутки внизу.
Итак, комментарии к коду должны быть такими, чтобы, если бы кто-нибудь вдруг стер весь код, оставив только эти самые комментарии, по ним нельзя было бы восстановить программу в первозданном виде. Это утверждение аналогично предыдущему: комментарии не должны лишь повторять то, что делает программа — скорее они должны описывать возможные тонкие места.
Задержим взгляд на последней мысли. Что такое вообще «тонкое место»? Как его можно распознать?.. Вообще говоря, никак — тут нужно положиться на интуицию или что-то, ее заменяющее. Предыдущий пример в свете сказанного мог бы выглядеть так (я перейду назад к «длинному» варианту, чтобы больше не мучаться с размером шрифта):
# $obj - список окон на рабочем столе.
# Считаем, сколько их.
my $elt=$obj->getFirst();
my $n=0;
# ВНИМАНИЕ! Следующее далее условие не работает,
# если список является кольцевым, а не
# оканчивается элементом undef.
while($elt) {
$n++;
$elt=$elt->getNext();
}
# Теперь $n - число окон.Внося дополнительный комментарий в этот «распухающий» демонстрационный код, мы тем самым оказываем помощь себе же, когда в будущем захотим переделать структуру списка в $obj.
Конечно, из кода и так ясно, что список не может быть закольцован — иначе цикл просто будет работать до бесконечности. Поэтому, конечно же, если вы когда-нибудь будете писать именно такой код, не используйте комментарий. Приведенный пример реально «работает» только в больших и сложных циклах.
Грамотный и добросовестный программист всегда ведет журнал изменений своего проекта, что тоже можно отнести к комментированию. Я его обычно не веду — лень. Тем не менее, могу посоветовать не вести такой журнал в начале каждого файла с исходниками, потому что не вести его в отдельном текстовом документе значительно сложнее. Старайтесь во время не ведения журнала записывать дату изменения (по прошествии пары лет будет очень интересно на нее взглянуть), его серьезность (хотя бы то, является ли это исправлением ошибки — BUGFIX — или же просто добавлением возможностей). Можно также указать, кто именно инициировал изменение (например, заказчик, или даже вы сами). В принципе, все это начнет постепенно очень сильно смахивать на CVS, и в этом плюс ведения журнала изменений: чем скорее вы приобщитесь в CVS и поймете необходимость его использования, тем лучше. Я пока так и не приобщился, но понимание необходимости уже на подходе.
Если в некотором месте кода вы нашли ошибку и хотите ее исправить, постарайтесь оставить на ее месте не «дыру» (то есть, пустое место), а комментарий, описывающий, в чем же была проблема. Особенно это относится к вашим же решениям улучшить тот или иной алгоритм в конкретной ситуации. Игнорирование этой рекомендации может привести к весьма курьезным случаям, когда вы 3 раза подряд наступаете на одни и те же грабли, «улучшая» код, а потом вдруг вспоминая, что именно это улучшение вы уже неоднократно делали и выяснялось: оно не может работать.
Стереотип четвертый: не вылезайте за правую границу поля редактирования.
Собственный опыт подсказывает: если вы изо всей силы избегаете писать код, символы которого «залезают» за правый край поля в редакторе (т.е. пересекают
80-й столбец), это может помочь лишь в одном случае — когда вам вдруг вздумается распечатать на принтере свой многотомный листинг. Зададимся вопросом:
а многие ли современные программисты печатают свои листинги на принтере?.. Вспомните, когда вы сами делали это в последний раз, и для чего (чтобы на досуге
почитать? чтобы сохранить «твердую копию» на всякий случай? чтобы убедиться, что алгоритм работает верно?).
Сначала кажется, что, если код не помещается на страницу по горизонтали, его будет трудно читать. Можете проверить сами: это не соответствует действительности. Если даже вы и заинтересуетесь одной из немногих строк, которые «не влезли», то наверно уж не побрезгаете пару раз нажать стрелку вправо или немного поелозить
линейкой прокрутки (для любителей меткой стрельбы). Конечно, я не призываю писать
код квадратиком
, а значит, 95% строк программы будут все-таки не длиннее 50-60 символов. И уж как писать эти
строки — дело ваше.
Длинные строки довольно удобны в следующих случаях.
* Некоторый небольшой фрагмент программы логически атомарен и не может изменяться без нарушения логики работы. Например, при использовании в Perl функции
sort
тело анонимной функции-сортировщика вполне может быть довольно длинным (приведенный пример сортирует содержимое директории в алфавитном порядке, чтобы
каталоги шли перед файлами): @r=sort { -d $a & !-d $b & -1 or -d $b & !-d $a & 1 or $a cmp $b } readdir(DIR);
* Фрагмент представляет собой строку текста небольшой длины, но из-за применения отступов ( табуляторов , показывающих уровень вложенности блоков кода) в коде ее правый край «не влез». Не буду на этот раз приводить пример — жалко ваши глаза, смотрящие в глубину браузера.
* Обстоятельства вынуждают вас написать некоторый очень нудный код, который, тем не менее, необходимо включать во все скрипты. Вы не хотите, чтобы в него кто-то вносил изменения, а также чтобы он мозолил вам глаза, занимая несколько строк. Например: use lib ($ENV{HOME}||"$ENV{DOCUMENT_ROOT}/.."). '/библиотеки';См.
пятую наблу, если интересуетесь, зачем кому-то может понадобиться такой код.
Если я вас так и не убедил, последний аргумент. Почему вы считаете, что вам мешает «вылезание» текста за правый край, в то время как на выход за нижний
край страницы вы не обращаете ровно никакого внимания, называя это «скроллингом»?.. Если вы скажете, что «у вас мышь с колесиком», то я отвечу: часто вэтом случае колесика 2, для вертикальной и горизонтальной прокрутки. Кроме того, стрелки на клавиатуре пока что никто не отменял.
большую часть текста с копиратил из статьи
http://dklab.ru/chicken/nablas/15.html
и ещё не очень адоптировал под basic, так, что ваши комментарии будут крайне не лишне.
Я видетели не очень понимаю perl, а придумать аналоги basic ещё не успел.
простые (строчные) комментарии
В начале комментария нужно поставить символ апострофа "'".
После него, можно писать всё, что угодно, до конца строки.
Вот например
- Код:
' напечатаем приветствие
print "Hello, world!"
Не обязательно отводить под комментарий отдельную строку, можо это делать и в тойже строке, что и инструкции.
- Код:
dim buf as wstring ptr ' указатель на буфер
Компилятор пропускает комментарии. Они не влияют на готовую программу.
сложные (блочные) комментарии
Есть так называемые блочные или сложные комментарии. Они позаимствованы из языка C. Эти комментарии должны иметь явное начало "/'" и явный конец "'/". Причём перенос строки уже не играет роли. Вот например
- Код:
print "1" /'234'/ & "5"
или можно так,
- Код:
print "1" /'
наш произвольный текст,
который мы можем располагать даже на нескольких строках.
'/ & "5"
Как видно из примеров, ничего сложного в них нету. Названы же они так только по аналогии с простыми. А раз есть простые и другие, то назвали их сложными.
как писать комментарии
Комментарии нужны только для сопровождения кода.
Многие люди придерживаются идеи о том, что хорошо написанная программа должна быть самодокументированной (не содержать комментариев, но, несмотря на это, легко читаться). К сожалению, в больших проектах этого добиться обычно не удается. Комментарии жизненно необходимы на всех этапах программирования, какдля вас, так и для остальных людей.
Если вы не писатель в душе, то ненавидите вставлять комментарии во время кодирования. В крайнем случае, откладываете это «на потом»: «Я вставлю комментарии после того, как программа заработает». Обычно это «потом» так и не настает, так что программа остается без комментариев, а значит, низкого качества (что бы там ни говорили, в большинстве случаев это так).
Про то, как желательно составлять комментарии, мы поговорим чуть ниже, а пока замечу одну деталь. Вы можете комментировать вашу программу, как вам вздумается. Но гораздо удобнее и приятнее будет придерживаться одного определенного стиля комментирования, как вы делаете это при написании кода. Четко выраженный стиль комментирования позволит также в перспективе создать программу, которая будет «шерстить» ваш код, выделяя из него комментарии и идентификаторы. Хороший пример этому — вставлять описания функций непосредственно перед ее заголовком. В дальнейшем с помощью автоматических утилит будет возможно выделить такие описания и даже создать на их основе нечто вроде документации.
Не думайте, что чем больше комментариев в программе, тем лучше.
Это утверждение прямо противоположно предыдущему, но никто и не говорил, что мы будем рассматривать только стереотипы из «одной корзины». Если вас иногда «заносит» и вы начинаете писать огромное количество комментариев в своем коде (а именно это частенько происходит со мной), если в вашей программе комментарии составляют более половины текста, время остановиться и задуматься. Налицо некоторая ошибка, но в чем же она заключается?..
И тут мы сталкиваемся с проблемой, у которой, вообще говоря, нет определенного решения. Можно лишь дать некоторые рекомендации и примеры того, когда следует писать комментарии, а когда — воздержаться, потому что и так очевидно, что делает программа. В этом смысле значительное преимущество имеют лица с раздвоением личности (я уже как-то писал, что эта особенность вредна для всего, чего угодно, но только не для программирования). Итак, написали пару строчек кода, — попробуйте взглянуть на них «свежим взглядом», как будто бы текст создали не вы, а кто-то еще. Если вам кажется, что код непонятен, то... Как вы думаете, что нужно сделать?..
Нет, не садиться комментировать на три страницы, ни в коем случае! Прежде всего, стоит подумать, нельзя ли участок программы написать получше. Возможно, это потребует перелопачивания некоторого объема кода выше и ниже только что вставленного фрагмента. В принципе, не стоит этого бояться: обычно любая реорганизация программы ведет к ее улучшению, а никак не к ухудшению (в крайнем случае, всегда можно вернуться к предыдущей архивной копии). К тому же, возможно, улучшение будет столь значительным, что в будущем вы скажете себе за него спасибо.
Предположим, вы все-таки решили вставить комментарий (естественно, это когда-нибудь произойдет). Что именно в нем написать?.. Не пытайтесь описать кусок кода изолированно: лучше опишите общими словами, что он делает, а также какие результаты будут получены после его выполнения. Вот пример неверного комментария:
' $elt хранит первый элемент списка.
my $elt=$obj->getFirst();
' Инициализируем нулем.
my $n=0;
' Пока текущий элемент существует...
while($elt) {
' Увеличить $n...
$n++;
# $elt = следующий элемент
$elt=$elt->getNext();
}Фактически, он может показаться верным с первого взгляда, но, тем не менее, тут допущена грубая ошибка, хуже которой — только вообще неработающий код.
Заметьте также, что комментарии составляют больше половины текста этой программы и загромождают ее. Если бы не выделение цветом, вообще трудно было бы разобрать, где код, а где примечания к нему.
Приведу теперь пример того, как можно откомментировать этот код. Наверняка мой вариант тоже не идеален, но он, по крайней мере, более информативен.
' $obj - список окон на рабочем столе.
' Считаем, сколько их.
my $elt=$obj->getFirst();
my $n=0;
while($elt) {
$n++;
$elt=$elt->getNext();
}
# Теперь $n - число окон.Наверное, вы поняли, что я сделал: просто убрал комментарии из мест, где и так все понятно. Перебирать связанный список можно
только одним способом — нет никакой необходимости это разъяснять. Зато нужно пояснить, что же в реальности хранится в той или иной переменной — ведь программист может случайно наткнуться на этот код, не глядя на всю его «предысторию».
Так как в этом примере читабельность кода между комментариями, в общем-то, не имеет особого значения, можно записать его короче и изящнее — вот так: # $obj - список окон на рабочем столе.
# Считаем, сколько их.
my $n=0;
for(my $e=$obj->first(); $e; $e=$e->next(), $n++) {}
# Теперь $n - число окон.
К моему большому сожалению, длинная строчка этого кода не влезала бы на страницу в браузере, если бы я не сократил имена методов до first() и next(). А
значит, пример произвел бы скорее негативное, чем положительное впечатление. Мне даже пришлось уменьшить шрифт, чтобы не появились линейки прокрутки внизу.
Итак, комментарии к коду должны быть такими, чтобы, если бы кто-нибудь вдруг стер весь код, оставив только эти самые комментарии, по ним нельзя было бы восстановить программу в первозданном виде. Это утверждение аналогично предыдущему: комментарии не должны лишь повторять то, что делает программа — скорее они должны описывать возможные тонкие места.
Задержим взгляд на последней мысли. Что такое вообще «тонкое место»? Как его можно распознать?.. Вообще говоря, никак — тут нужно положиться на интуицию или что-то, ее заменяющее. Предыдущий пример в свете сказанного мог бы выглядеть так (я перейду назад к «длинному» варианту, чтобы больше не мучаться с размером шрифта):
# $obj - список окон на рабочем столе.
# Считаем, сколько их.
my $elt=$obj->getFirst();
my $n=0;
# ВНИМАНИЕ! Следующее далее условие не работает,
# если список является кольцевым, а не
# оканчивается элементом undef.
while($elt) {
$n++;
$elt=$elt->getNext();
}
# Теперь $n - число окон.Внося дополнительный комментарий в этот «распухающий» демонстрационный код, мы тем самым оказываем помощь себе же, когда в будущем захотим переделать структуру списка в $obj.
Конечно, из кода и так ясно, что список не может быть закольцован — иначе цикл просто будет работать до бесконечности. Поэтому, конечно же, если вы когда-нибудь будете писать именно такой код, не используйте комментарий. Приведенный пример реально «работает» только в больших и сложных циклах.
Грамотный и добросовестный программист всегда ведет журнал изменений своего проекта, что тоже можно отнести к комментированию. Я его обычно не веду — лень. Тем не менее, могу посоветовать не вести такой журнал в начале каждого файла с исходниками, потому что не вести его в отдельном текстовом документе значительно сложнее. Старайтесь во время не ведения журнала записывать дату изменения (по прошествии пары лет будет очень интересно на нее взглянуть), его серьезность (хотя бы то, является ли это исправлением ошибки — BUGFIX — или же просто добавлением возможностей). Можно также указать, кто именно инициировал изменение (например, заказчик, или даже вы сами). В принципе, все это начнет постепенно очень сильно смахивать на CVS, и в этом плюс ведения журнала изменений: чем скорее вы приобщитесь в CVS и поймете необходимость его использования, тем лучше. Я пока так и не приобщился, но понимание необходимости уже на подходе.
Если в некотором месте кода вы нашли ошибку и хотите ее исправить, постарайтесь оставить на ее месте не «дыру» (то есть, пустое место), а комментарий, описывающий, в чем же была проблема. Особенно это относится к вашим же решениям улучшить тот или иной алгоритм в конкретной ситуации. Игнорирование этой рекомендации может привести к весьма курьезным случаям, когда вы 3 раза подряд наступаете на одни и те же грабли, «улучшая» код, а потом вдруг вспоминая, что именно это улучшение вы уже неоднократно делали и выяснялось: оно не может работать.
Стереотип четвертый: не вылезайте за правую границу поля редактирования.
Собственный опыт подсказывает: если вы изо всей силы избегаете писать код, символы которого «залезают» за правый край поля в редакторе (т.е. пересекают
80-й столбец), это может помочь лишь в одном случае — когда вам вдруг вздумается распечатать на принтере свой многотомный листинг. Зададимся вопросом:
а многие ли современные программисты печатают свои листинги на принтере?.. Вспомните, когда вы сами делали это в последний раз, и для чего (чтобы на досуге
почитать? чтобы сохранить «твердую копию» на всякий случай? чтобы убедиться, что алгоритм работает верно?).
Сначала кажется, что, если код не помещается на страницу по горизонтали, его будет трудно читать. Можете проверить сами: это не соответствует действительности. Если даже вы и заинтересуетесь одной из немногих строк, которые «не влезли», то наверно уж не побрезгаете пару раз нажать стрелку вправо или немного поелозить
линейкой прокрутки (для любителей меткой стрельбы). Конечно, я не призываю писать
код квадратиком
, а значит, 95% строк программы будут все-таки не длиннее 50-60 символов. И уж как писать эти
строки — дело ваше.
Длинные строки довольно удобны в следующих случаях.
* Некоторый небольшой фрагмент программы логически атомарен и не может изменяться без нарушения логики работы. Например, при использовании в Perl функции
sort
тело анонимной функции-сортировщика вполне может быть довольно длинным (приведенный пример сортирует содержимое директории в алфавитном порядке, чтобы
каталоги шли перед файлами): @r=sort { -d $a & !-d $b & -1 or -d $b & !-d $a & 1 or $a cmp $b } readdir(DIR);
* Фрагмент представляет собой строку текста небольшой длины, но из-за применения отступов ( табуляторов , показывающих уровень вложенности блоков кода) в коде ее правый край «не влез». Не буду на этот раз приводить пример — жалко ваши глаза, смотрящие в глубину браузера.
* Обстоятельства вынуждают вас написать некоторый очень нудный код, который, тем не менее, необходимо включать во все скрипты. Вы не хотите, чтобы в него кто-то вносил изменения, а также чтобы он мозолил вам глаза, занимая несколько строк. Например: use lib ($ENV{HOME}||"$ENV{DOCUMENT_ROOT}/.."). '/библиотеки';См.
пятую наблу, если интересуетесь, зачем кому-то может понадобиться такой код.
Если я вас так и не убедил, последний аргумент. Почему вы считаете, что вам мешает «вылезание» текста за правый край, в то время как на выход за нижний
край страницы вы не обращаете ровно никакого внимания, называя это «скроллингом»?.. Если вы скажете, что «у вас мышь с колесиком», то я отвечу: часто вэтом случае колесика 2, для вертикальной и горизонтальной прокрутки. Кроме того, стрелки на клавиатуре пока что никто не отменял.
большую часть текста с копиратил из статьи
http://dklab.ru/chicken/nablas/15.html
и ещё не очень адоптировал под basic, так, что ваши комментарии будут крайне не лишне.
Я видетели не очень понимаю perl, а придумать аналоги basic ещё не успел.
Eric-S- Сообщения : 738
Дата регистрации : 2008-08-06
Возраст : 41
Откуда : Россия, Санкт-Петербург -
Похожие темыСтраница 1 из 1
Права доступа к этому форуму:
Вы не можете отвечать на сообщения