зачем пишут комментарии в программах подумайте как комментирование можно использовать при поиске

Комментарии

Многие сегодня хотят стать программистами. Хотят. Но ничего не делают для этого. Не делают даже простых вещей. Не хотят даже прочитать книжку из 10 страниц. В итоге так и остаются никем. Потому что мечты не сбываются никогда. Сбываются только планы… Подробнее.

Вы наверняка уже знаете, что такое комментарии. Но, быть может, знаете об этом вы ещё не всё.

Зачем нужны комментарии?

Во-первых, в начале каждого модуля или программы программист обычно указывает автора, версию, дату создания и т.п.

Во-вторых, в больших программах довольно сложно ориентироваться. Поэтому комментарии в исходных текстах очень помогают разобраться с тем, где кончается один блок кода и начинается другой.

В-третьих, есть сложные алгоритмы, разобраться в которых без комментариев трудно не только другому человеку, но и самому автору через пару недель, а тем более лет.

Комментарии Free Pascal могут быть такими:

<Это комментарий в фигурных скобках>
(* И это тоже комментарий, но уже в круглых скобках со звёздочками *)
// А это комментарий в стиле С++

Как видите, Free Pascal поддерживает несколько видов комментариев. Последний пример – это комментарии в стиле С++ (в обычном Паскале такие комментарии не предусмотрены).

Комментарий в стиле С++ начинается двумя косыми чертами и продолжается до конца строки. То есть комментарии Паскаля открываются и закрываются скобками, а комментарий в стиле С++ открывается двумя косыми чертами и действует до конца строки. А это значит, что если вы используете комментарии в стиле С++, то в начале каждой строки с комментарием вам нужно ставить две косые черты.

В каком стиле писать комментарии – это личное дело каждого. Однако лучше привыкать писать их с первых шагов в изучении программирования. Очень часто бывает, что приходится отложить работу над программой на какой то срок, либо адаптировать старую программу к новым условиям. Вернувшись к своей программе через месяц, вы уже вряд ли будете помнить ход своих мыслей в момент работы над программой, и придётся заново разбираться с исходными кодами. В некоторых случаях бывает проще написать новую программу, чем разбираться с исходными кодами старой (особенно если она плохо документирована).

Что ещё нужно знать о комментариях?

Комментарии могут быть вложенными. Например,

Как видите, вложенный комментарий ничем не отличается от обычного комментария, за исключением того, что он находится внутри другого комментария

В классических компиляторах Паскаля (например, в Turbo Pascal и Delphi), тип вложенных комментариев ОБЯЗАТЕЛЬНО должен отличаться от типа комментария, в который вложен комментарий.

То есть такой комментарий

Вызовет ошибку во время компиляции.

Free Pascal допускает вложенные комментарии одинакового типа. Хотя при компиляции в таком случае будет выдано предупреждение. Однако не следует этим злоупотреблять, так как это плохо скажется на переносимости кода.

Кроме комментариев в фигурных скобках также могут быть директивы компилятора. Выглядят они примерно так:

То есть директива компилятора начинается со знака доллара. Поэтому никогда не начинайте свои комментарии со знака доллара. Это может привести к проблемам.

Ну и напоследок привожу текст программы с разными видами комментариев.

program comment; <$mode objfpc> <$H+>//Это директива компилятора uses <$IFDEF UNIX> <$IFDEF UseCThreads>//Это тоже директива cthreads, <$ENDIF> <$ENDIF>//Это тоже директива Classes < you can add units after this >; //Это комментарий begin //Это однострочный комментарий < Этот комментарий может занимать несколько строк>(* Это тоже многострочный комментарий *) < А вот так < делать нельзя в режиме Turbo Pascal и Delphi>потому что вложенные комментарии могут быть только разных видов > < Правильный (* Вложенный комментарий *) лучше делать так >end.

Создайте программу из листинга 17.1. Откомпилируйте её и убедитесь, что всё работает без ошибок.

В директиве компилятора, которая определяет режим компиляции, замените режим objfpc на режим tp или delphi. Попробуйте откомпилировать программу. Объясните, почему возникает ошибка во время компиляции.

Источник

Комментирование в C: зачем ставить комментарии в коде своей программы

Комментарии в С — это специальные пояснительные строки, которые помогают зафиксировать, а потом через время понять смысл написанного кода. Комментарии рассчитаны для людей и никак не воспринимаются компилятором или интерпретатором.

Комментарии в С могут писаться в одну или несколько строк. В зависимости от этого синтаксис комментариев будет отличаться, об этом чуть ниже.

Комментарии в С

Для чего нужны комментарии в С?

Комментарии в С и в других языках программирования нужны:

Чтобы не запутаться при разработке собственных библиотек, функций, методов и переменных.

Чтобы описать сложные алгоритмы или формулы. Если ваша программа завязана на сложных математических расчетах, то комментарии будут незаменимы.

Как оформить комментарии в С?

Однострочные комментарии в С обозначаются двумя наклонными линиями «//» только в начале самого комментария.

Многострочные комментарии в С обозначаются с двух сторон, отмечая начало и конец комментария. В качестве обозначения таких комментариев применяют сочетание наклонной линии и «звездочки». Многострочный комментарий будет выглядеть так: « /*многострочные комментарии в С*/ ».

По каким правилам пишутся комментарии в С?

Изначально можно подумать, что раз комментарии в С не читаются интерпретаторами и компиляторами, то можно их писать где хочешь и сколько хочешь, просто правильно оформляя. Так никто не запрещает поступать, но есть общепринятые рекомендации по написани ю комментариев. Лучше и х придерживаться, чтобы ваш код был не только эффективным, но и правильно оформленным.

Рекомендации о том, как писать комментарии в С:

Место написания. Комментарии в С рекомендуется писать справа от строки, к которой они относятся, если комментарий короткий ; и сверху над кодом, к которому они относятся, если комментарий многострочный.

Область комментирования. Комментируется не все подряд, а только основные и значимые части кода: функция, модуль, константа, глобальная переменная, интерфейс, класс и др.

Размер комментария. Комментарии в С не должны выглядеть как целые поэмы. Нужно писать максимально коротко и только по делу. Любой комментарий, который не несет смысла, не должен присутствовать в коде.

Кстати, все комментарии в С по смысловой нагрузке можно разделить на 2 группы:

Для пояснения. Сюда включают все комментарии в С, которые разъясняют логику поведения кода, функции, алгоритма и т. д. Наличие комментариев такого рода регламентируются самим разработчиком. Именно они обеспечивают дальнейшее удобство взаимодействия с кодом и пояснение его составляющих.

Когда нужны комментарии в С, а когда — нет?

Однако при этом не стоит просто нагружать документ ненужными комментариями. То есть не т необходимости комментировать то, что и так очевидно. Пример того, как делать не надо:

Для переменной age указываем значение 45

То есть тут и так все понятно, поэтому не нужно засорять код такими комментариями. Изначально важно стремиться к тому, чтобы писать код, не требующий подробного комментирования. А если комментарий и пишется, то только по делу.

Заключение

Запомните! Лучше писать простой и понятный код, чем писать непонятный и запутанный, но с большим количеством комментариев.

Мы будем очень благодарны

если под понравившемся материалом Вы нажмёте одну из кнопок социальных сетей и поделитесь с друзьями.

Источник

Лучшие практики написания комментариев к коду

Известный профессор МТИ Гарольд Абельсон сказал: «Программы нужно писать для того, чтобы их читали люди, и лишь случайно — чтобы их исполняли машины». Хотя он намеренно преуменьшил важность исполнения кода, однако подчёркивает, что у программ две важные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и с одинаковой лёгкостью воспринимают все синтаксически корректные программы. У людей всё иначе. Одни программы нам воспринимать легче, чем другие, и мы ищем комментарии, которые помогут нам разобраться.

Есть множество источников информации, помогающих программистам писать более качественный код — книги, сайты, статические анализаторы. Но гораздо меньше источников посвящено повышению качества комментариев. Легко измерить их количество в программе, но качество оценить сложно, и два этих параметра не обязательно взаимосвязаны. Плохой комментарий хуже отсутствия комментария. Вот несколько правил, которые помогут вам найти золотую середину.

Как писал Питер Фогель:

Первое правило: комментарии не должны дублировать код

Многие начинающие программисты пишут слишком много комментариев, потому что их к этому приучили. Я видел, как старшекурсники на факультете информатики добавляют комментарии к каждой закрывающей скобке, чтобы показать закрытие блока:

Я слышал о преподавателях, которые требуют от студентов комментировать каждую строку кода. Для совсем новичков это может быть оправдано, однако такие комментарии как боковые колёсики на детском велосипеде, которые по мере роста надо снять.

Неинформативные комментарии вредны, потому что:

Комментарий не добавляет полезной информации и требует усилий по поддержке.

Требования комментировать каждую строку справедливо высмеяли на Reddit:

Второе правило: хорошие комментарии не оправдывают непонятный код

Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:

Комментарий был бы не нужен, если дать переменной правильное название:

Как написали Керниган и Плогер в книге «The Elements of Programming Style»: «Не комментируйте плохой код, а переписывайте его».

Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде

Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:

Отладка вдвое труднее первоначального написания кода. Поэтому если вы пишете код как можно умнее, то вы по определению не настолько умны, чтобы его отладить.

Предупреждение читателям, чтобы они держались подальше от вашего кода, сродни включению аварийных огней: признание в том, что вы делаете что-то незаконное. Лучше перепишите код так, чтобы вы сами понимали его достаточно, чтобы объяснить другим. Или ещё лучше, чтобы его вообще не требовалось объяснять.

Четвёртое правило: комментарии должны исключать путаницу, а не вносить её

Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:

[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.

Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.

Пятое правило: объясняйте в комментариях не идиоматический код

Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):

Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:

Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.

Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.

Если вы такой же, как и большинство программистов, то иногда вы используете найденный в сети код. Добавляйте ссылку на исходник, чтобы будущие читатели имели полный контекст, например:

Если перейти по ссылке, то вы обнаружите, что:

Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.

Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.

Вы также можете ссылаться на оказавшиеся полезными руководства в качестве благодарности их авторам и ради экономии времени читателей:

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

Конечно, не все ссылки ведут на Stack Overflow.

Ссылки на стандарты и другую документацию помогут читателям понять проблему, которую решает ваш код. Хотя эта информация может храниться в проектной документации, однако удачно размещённый комментарий станет своевременным указателем. В приведённом примере ссылка подсказывает, что RFC 4180 обновили на RFC 7111, это полезная информация.

Восьмое правило: исправляя баги, добавляйте комментарии

Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:

Комментарий не только помогает понять код в конкретных методах, но и определить, нужен ли ещё этот код и как его тестировать. Также комментарий может ссылаться на систему отслеживания ошибок:

Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).

Девятое правило: помечайте комментариями незаконченные реализации

Иногда необходимо проверять код, даже несмотря на его ограничения. Хотя может быть заманчиво не рассказывать о недостатках своего кода, лучше сделать это явно, например, в комментарии TODO:

Стандартный формат для таких комментариев помогает оценить и адресовать технический долг. Ещё лучше, если добавите задачу в систему отслеживания ошибок и вставите ссылку в комментарий.

Источник

Зачем комментировать исходный код и как это делать правильно

Как не забыть о том, что вы имели ввиду полгода назад, когда писали этот программный код? Разбираемся с использованием комментариев.

Комментарии — поясняющие строки в программном коде, которые позволяют понять смысл написанного. Они пишутся для людей, но игнорируются компиляторами и интерпретаторами.

Знакомый, наверно, каждому пример со словами на русском или английском языке после двух слешей — так обычно выглядят комментарии:

Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.

Чем комментарии могут помочь программисту

Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:

Как комментарии оформляют в коде

Комментарии бывают совсем короткими, длиной не более строки, и большими, многострочными.

Однострочные выделяют одиночным символом в начале и продолжают до конца строки, а многострочные могут иметь любую длину, но поддерживаются не всеми языками. Их отмечают специальными символами в начале и конце текста, например, /* и */.

Для выделения комментариев в коде используют разные символы:

Правила, которых принято придерживаться

У разработчиков принято использовать при комментировании несколько простых правил. Так легче работать — больше пользы и не нужно плодить лишние строки кода.

1. Комментарии помещаются прямо над кодом, к которому они относятся. Так проще понять, о чём речь, не вникая в содержание каждой строчки. Совсем короткие пояснения можно писать справа.

2. Комментируют все основные элементы кода: модули, функции, константы, глобальные переменные, интерфейсы, классы и их составные элементы (методы, свойства, константы).

3. Пишут коротко и по делу. Комментарии без смысловой нагрузки страшно раздражают. Не нужно писать комментарии типа «это гениальный код», «таблица1», «! №; %:? *» и подобные.

4. Нельзя, чтобы комментарии оскорбляли кого-то или содержали слова, которые не поймёт технарь. В поддержку движения Black Lives Matter Twitter в своем коде решил не использовать слова slave, master и blacklist. Кто-то из россиян, возможно, улыбнётся, но стандарт есть стандарт.

Документирующие и поясняющие комментарии

В зависимости от того, для чего нужны комментарии, их условно делят на два вида:

Пример на языке Java:

Из такого комментария сразу ясно, что делает программа. Не нужно вникать в исходный текст и изучать техническую документацию. Это особенно важно, если вы работаете в команде и хотите сэкономить время коллег.

Комментарии-описания иногда мешают разработчикам и отвлекают внимание от основного кода. Поэтому в большинстве современных редакторов есть возможность свернуть или скрыть комментарии.

Как комментируют функции и библиотеки

В комментариях к файлам и библиотекам указывают информацию о проекте, назначении модуля, заносят в них имя разработчика, номер версии продукта и лицензию на программное обеспечение.

Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:

Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:

Пример из той же библиотеки Lodash:

Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:

К прикладным процедурам, функциям и классам делайте информативные и понятные заголовки с описанием всех входных и выходных параметров.

Как автоматизировать создание комментариев

В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:

Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.

Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.

При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.

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

Когда нужны пояснения в коде, а когда — нет

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

Но иногда эти пояснения только ухудшают наглядность кода, бывают бессмысленны и даже вредны. Например, совершенно не нужны комментарии, просто пересказывающие действия программы:

Если вы вставили промежуточные комментарии для отладки или объяснения результатов, после окончания работы их нужно убрать. Иначе они будут захламлять код.

Например, функция вычисляет окончательную сумму, прибавляя проценты к основной. Для проверки программист вывел на экран промежуточный результат, а после закомментировал ненужный фрагмент.

После отладки их лучше удалить, оставив строки:

Простой код, без многочисленных циклов, ветвлений и переходов, пишут и структурируют так, чтобы никаких дополнительных пояснений к нему не требовалось.

Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.

Пример на языке JavaScript:

Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).

Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:

Это неудачный комментарий: непонятно, зачем количество умножать на 2.

Правильно будет так:

В любом случае, старайтесь писать поясняющие комментарии как можно реже.

Комментарии в сложном коде и рефакторинг

В сложной и запутанной программе не обойтись без поясняющих комментариев. Но иногда лучше упростить сам код: разбить на отдельные функции, уменьшить размеры элементов, упростить циклы и так далее. А самим функциям, константам и переменным дать «говорящие» имена, объясняющие их назначение.

Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a

Весь этот громоздкий кусок кода можно значительно упростить, просто убрав блок if-else:

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

Рефакторинг меняет структуру кода, оставляя неизменной его суть. Он повышает читаемость кода и облегчает процесс его доработки. Рефакторинг не заменяет комментирование, но с ним комментариев нужно намного меньше.

Что в итоге

Комментарии — отличная штука. Они помогают команде разработчиков работать над общим проектом. А если программист один, позволят ему даже через много лет вспомнить ход своих мыслей. Но комментариев должно быть мало, иначе они превратятся во флуд.

Комментировать нужно основные элементы кода, неочевидные решения, сложные бизнес-процессы, тонкости решений и тому подобное. Не пишите комментарии, объясняющие, что и как делает процедура или функция, — это бессмысленно.

И помните, что комментарий — не панацея, он не спасёт плохой код, даже если сделает его понятнее. Сложные и запутанные фрагменты сокращайте и делайте рефакторинг, а комментируйте по минимуму.

Научиться использовать комментарии, верно документировать исходный код, писать его понятным для коллег и читабельным даже через много лет вы можете на наших курсах по программированию. Выбирайте любой и становитесь профессионалом.

Источник