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

 

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

 

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

 

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

 

В этой статье мы рассмотрим различные методы комментирования, поддерживаемых в Python.

 

Но, пожалуй начнем с поиска смысла комментирования. Итак, какой смысл комментирования кода?

 

Смысл комментирования кода

 

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

 

Наиболее частыми причинами отсутствия комментария к коду, могут быть:

 

1. Нежелание комментировать свой код, с уверенностью на то, что если я его писал, то зачем мне это комментировать? Итак понятно.
2. Отсутствие свободного времени, когда сроки сдачи проекта поджимают.

 

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

 

Очень часто многие приложения проходят многочисленный процесс улучшений и изменений в коде. Порой бывает даже так, что код с одного приложения заимствуется для другого. Дабы не изобретать велосипед снова, очень часто происходит заимствование и взаимообмен кода разработчиками. Например, ярким примером заимствования кода, могут служить приложения, распространяемые под лицензией GNU/GPL и прочими схожими, которые в народе получили название Free Soft.

 

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

 

Или, ситуация совсем противоположная, когда вам необходимо будет дополнить своё приложение готовым участком кода. Как думаете, на сколько у вас хватит сил и терпения для понимания многочисленных примеров кода без комментариев, взятых с GitHub или Stackoverflow, в поиске необходимого? Уверен, что такой, не совсем приятный процесс, вы запомните надолго.

 

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

 

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

 

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

 

Типы комментариев

Комментарии в Python коде, как и в большинстве языков программирования, делятся на типы:

 

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

 

В свою очередь, все вышеперечисленные типы делятся на подтипы: однострочные и блочные (многострочные) комментарии.

 

• Однострочные комментарии.

 

Применяются:

 

– в начале пустой строки сверху над кодом;

– в конце строки после кода (встроенный комментарий);

– для закомментирования кода, применяются перед кодом в качестве символа #.

• Блочные комментарии. Блок комментариев обычно объясняет код (весь, или только некоторую часть), идущий после блока, и должен иметь тот же отступ, что и сам код. Каждая строчка такого блока должна начинаться с символа # и одного пробела после него (если только сам текст комментария не имеет отступа).

 

Абзацы внутри блока комментариев разделяются строкой, состоящей из одного символа #.

 

Применяются:

 

–  в начале пустой строки сверху над кодом;

–  для закомментирования кода, применяются перед кодом в качестве символа #.

Обращаю внимание, что в конце строки после кода, применяется только однострочные короткие комментарии, но старайтесь их использовать реже. Ведь такие комментарии очень часто отвлекают от чтения, если они объясняют очевидное.

Синтаксис комментариев Python

 

Правило №1. Комментарии в Python начинаются с хеша (символа #), после которого ставится один пробел.

 

Пример однострочного комментария:

 

 

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

 

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

 

Неважно сколько строк займет ваш комментарий, это будет одна или десять, он всегда должен начинаться только с этого символа.

 

Блок комментариев обычно объясняет код (весь, или только некоторую часть), идущий после блока, и должен иметь тот же отступ, что и сам код. Каждая строчка такого блока должна начинаться с символа # и одного пробела после него (если только сам текст комментария не имеет отступа).

 

Абзацы внутри блока комментариев разделяются строкой, состоящей из одного символа #.

 

Пример блочного комментария:

 

 

Хотя сейчас можно встретить в сети практику применения символа трёх кавычек     ‘ ’ ’ для обозначения блочного комментария в Python коде.

 

Пример комментирование блочного кода тремя кавычками:

 

 

И пример закомментированного блока кода:

 

 

На мой взгляд, такая практика является ошибочной и крайне нежелательной. Использование кавычек для обозначения комментария, противоречит стандарту PEP 8 (PEP 8 — Style Guide for Python Code) языка Python, и игнорирование этого требования, возлагает большую ответственность на плечи самого разработчика за работоспособность кода в целом.

 

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

 

В соответствии с вышеуказанным стандартом PEP 8, тройные кавычки  “ “ “ допускается использовать только для определения строки документации, но не для определения блочного комментария. Это важно запомнить.

 

Правило №2. Длина комментария не может составлять больше 75 символов.

 

Правило №3. Комментарий допускается писать или в начале новой строки или в конце строки после кода, за исключением закомментирования кода.

 

Пример комментария в начале строки:

 

 

Встроенный комментарий, должен отделяться от кода не менее двумя отступами.

 

Пример встроенного комментария в конце строки после кода:

 

 

Правило №4. Для закомментирования кода, символ # вставляется в строке перед кодом.

 

Пример закомментированного однострочного кода:

 

 

И блочного кода:

 

 

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

 

Пример недопустимого указания комментария внутри кода:

 

Общие советы

• Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда исправляйте комментарии, если меняете код!
• Комментарии должны являться законченными предложениями. Если комментарий — фраза или предложение, первое слово должно быть написано с большой буквы, если только это не имя переменной, которая начинается с маленькой буквы (никогда не изменяйте регистр переменной!).
• Если комментарий короткий, можно опустить точку в конце предложения. Блок комментариев обычно состоит из одного или более абзацев, составленных из полноценных предложений, поэтому каждое предложение должно оканчиваться точкой.
• Ставьте два пробела после точки в конце предложения.
• Программисты, которые не говорят на английском языке, пожалуйста, пишите комментарии на английском, если только вы не уверены на 120%, что ваш код никогда не будут читать люди, не знающие вашего родного языка.

 

Читайте также:

Легко ли научиться программировать?