Программистам регулярно приходится читать, анализировать и писать код. Некоторые фрагменты легче писать и выполнять, чем другие. Чем вразумительнее код, тем быстрее его можно понять и использовать, а также создавать продукты на его основе. Способность писать грамотный код — необходимый навык для любого программиста и специалиста по исследованию данных.
Не менее важно уметь писать понятные комментарии. Конечно, если вы овладеете искусством написания читабельного кода, количество комментариев значительно сократится. Тем не менее полностью отказаться от них не получится.
Комментарии — это основная часть любого хорошего кода. Без них придется потратить немало времени на чтение и понимание. Отсутствие примечаний так же плохо, как и их чрезмерное количество: если в файлах содержится 50% и более комментариев, это означает, что код не так хорош, как кажется.
Стать хорошим комментатором несложно, но для этого нужно много практиковаться. Если вы читаете эту статью, вы либо программист, либо специалист по анализу данных, либо работаете в сфере технологий. Это значит, что ваша профессия предполагает частое написание и прочтение большого количества кода.
Итак, как же научиться корректному комментированию? Эти 5 лайфхаков помогут вам стать хорошим комментатором и поднимут ваши навыки на новый уровень.
#1. Будьте кратки и лаконичны, пишите по делу
Лучше меньше, чем больше — это правило отлично подходит к комментированию кода. Старайтесь не объяснять слишком подробно каждый этап. Комментарии должны быть короткими: не более 3 предложений для пояснения классов и функций и одного предложения для внутристрочного комментария.
Если код хорошо написан, вам не понадобится много комментариев для его объяснения. Вам нужно будет лишь дать понять пользователю (или коллеге-программисту), почему вы приняли то или иное решение и какова общая функциональность различных фрагментов.
Как правило, при написании комментариев (docstring) для класса, следует включать в них краткое описание и дату последней модификации. Это требование необходимо соблюдать для поддержания порядка и единообразия оформления кода в рамках конкретного сообщества программистов. В то же время комментарий для функции должен содержать описание ее назначения, параметров и результатов.
#2. Сохраняйте единый стиль для каждого уровня
Часто код делится на такие элементы, как блоки, функции, классы, модули, библиотеки и т. д. Каждый из них можно рассматривать как отдельный уровень. Поэтому, когда вы пишете комментарии, лучше разработать определенный стиль для каждого уровня и поддерживать его на всем протяжении кода.
Таким образом, вам нужно будет использовать один и тот же стиль написания docstring для всех функций кода. То же самое относится и к внутристрочным комментариям. Это поможет любому читающему быстро просмотреть код и понять его структуру, не прибегая к углубленному чтению.
#3. Пишите комментарии до или во время написания кода, а затем редактируйте их
Одна из самых больших ошибок новичков, которые только учатся писать код, заключается в том, что они сначала создают код, а затем просматривают его и пишут комментарии. Проблема в том, что часто на написание кода уходит какое-то время — дни или даже месяцы. Поэтому когда мы подходим к этапу написания комментариев, мы уже не помним, почему приняли те или иные решения.
Лучше всего писать комментарии в процессе работы. Некоторые программисты считают даже, что комментарии следует писать до ее начала: так они будут служить ориентиром в дальнейшем.
Но, на мой взгляд, параллельное создание кода и комментариев — это наиболее эффективный подход с точки зрения затрат времени и усилий. Поэтому создавайте комментарии в процессе написания кода, а в конце редактируйте их по мере необходимости.
#4. Старайтесь делать комментарии понятными
Комментарии предназначены не только для людей, которые будут читать ваш код, но и для вас. В будущем вам придется поддерживать код и расширять его в ходе следующих этапов разработки. Если комментарии написаны понятно, это поможет и другим разработчикам, и вам.
#5. Помните о простоте
И наконец, самый очевидный совет — следите за простотой комментариев. Код должен быть простым, чтобы не пришлось объяснять его с помощью множества комментариев, а сами комментарии должны быть простыми и понятными, чтобы другим пользователям было легко им следовать.
Один из основных принципов программирования гласит: “пусть ваш код говорит сам за себя”. Хотя это правило особенно активно поддерживается программистами, которые не любят писать комментарии, нельзя полностью отказаться от их написания. Тем не менее их количество можно значительно уменьшить, если писать более простой код.
Выводы
Чтобы стать успешным специалистом по исследованию данных, необходимо овладеть различными навыками, первым из которых является программирование. Хороший программист умеет писать понятный код и краткие комментарии к нему. И то, и другое одинаково важно. Однако большинство людей уделяют больше внимания развитию навыков написания кода и пренебрегают искусством создания комментариев.
Как и в любом другом навыке, единственный способ совершенствоваться в комментировании кода — это постоянная практика. Прежде всего перечитайте комментарии, которые вы считаете удачными, и подумайте, почему они вам понравились. Часто наиболее оптимальными оказываются короткие, четкие и описательные комментарии.
В этой статье мы рассмотрели 5 советов, которые поднимут ваши навыки написания комментариев на новый уровень. Помните: комментарии не предназначены для объяснения кода пользователям. Наоборот, код используется для объяснения комментариев компьютеру.
Читайте также:
- 5 весомых причин познакомиться с паттерном “Компоновщик”
- 5 антипаттернов на языке функционального программирования
- Магическая формула для улучшения навыков программирования
Читайте нас в Telegram, VK и Яндекс.Дзен
Перевод статьи Sara A. Metwalli: 5 Tips to Write Better Comment In Your Code
