Пишите комментарии: Пишите или пишете — как правильно? | Образование

Содержание

Пишите или пишете — как правильно? | Образование | Общество

15.05.2017 12:45

Есения Павлоцки

Примерное время чтения: 4 минуты

350993

Сюжет Говорим и пишем по-русски грамотно

Shutterstock.com

Отвечает Есения Павлоцки, лингвист-морфолог, эксперт института филологии, массовой информации и психологии Новосибирского государственного педагогического университета.

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

Самым простым решением оказываются вопросы, которые следует задать к глаголу: что делаете (пишете) или что делайте (пишите)? Первый адресуется к действию в настоящем, а второй к императиву, повелительному наклонению.

Если речь идет о глаголе в настоящем времени, то употребляем пишете.

Почему? Глагол писать относится к первому спряжению (глагол на -ать). Согласно закономерности (а это результат сложных изменений в ходе развития нашего языка), в личных окончаниях глаголов первого спряжения мы пишем Е (-ем, -ешь, -ете, -ет).

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

Учить наизусть иррациональные (без погружения в историческую грамматику) закономерности действительно нелегко. В личных окончаниях I спряжения у нас Е, а II спряжения — И. Хорошо, но почему? Ответ на вопрос совсем не прост, и мы запоминаем это как аксиому.

А тем временем система, которая заставляет нас ломать голову — дышат или дышут, пишите или пишете, борятся

или борются — уже упрощена сама собой.

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

Более того, спряжение форм настоящего времени в древнерусском языке было представлено тремя типами — I, II и нетематическим, которые различались лишь отдельными окончаниями.

Горшкова К. В., Хабургаев Г. А. Историческая грамматика русского языка, 1981.

В общем, ситуация на сегодня, очевидно, куда более простая. Но от этого не легче, и, конечно, проще запомнить то, что понятно. И если языковая интуиция — последняя надежда — не сложилась, то мучениям со склонениями, спряжениями и -ться/-тся не избежать.

Но, увы, это данность. Когда возникает вопрос «откуда это взялось», следует вспомнить: историческая грамматика похожа на известное английское стихотворение «Дом, который построил Джек», и уяснить пару алгоритмов намного проще, чем понять, что к ним привело.

Итак, в глаголе настоящего времени мы видим Е — пишете. Если же перед нами императив — пишите с И. От императива в целом отталкиваться проще: если нам нужно употребить напишете, то время уже не настоящее. Получается, что опять возникает путаница. С повелительным наклонением таких проблем не будет: пишите, напишите!

Еще один прием-подсказка — это ударение. Пишете — безударная позиция и Е, а пишите — ударная, И. Можно запомнить, с какой буквой сочетается ударение на определенном слоге, и избавиться от вопроса раз и навсегда.

Итак, императив пишите (я прошу вас/указываю вам писать) и глагол в форме настоящего времени пишете (то, что вы сейчас/в целом делаете).

Примеры употребления: Немедленно пишите, что вы отказываетесь; пишите мне чаще / Здесь вы пишете ваше имя; вы очень красиво пишете.

Ошибки есть даже в учебниках! Учитель русского языка о росте безграмотности →
Филолог о причинах безграмотности россиян →
До скольки и который час — как правильно? →

русский язык

Следующий материал

Также вам может быть интересно

Преумножить или приумножить — как правильно?
Риэлтор или риелтор — как правильно?
Андрей Шулимов: «Язык жестов людям понять легче, чем человеческую речь»

Новости СМИ2

Комплекты цепь + браслет (длину пишите в комментарии)

Доставка 20 марта

2116 отзывов

Набор «Gold Fish» 1,4 см (Ж2)

Необыкновенный набор из дубайского золота «Gold Fish». В набор входят серьги, браслет и цепочка Цеп…

В архиве Товар продан

Набор «Gold Fish» 1,0 см (Ж2)

Необыкновенный набор из дубайского золота «Gold Fish». В набор входят браслет ,цепочка и серьги Це…

В архиве Товар продан

Набор цепь+браслет «Золотые оковы (ж2)

Цепочка и браслет из дубайского золота с классическим соединением звеньев Длина: от 40 до 60см Ши…

В архиве Товар продан

Набор «Мадонна» 0,5 см. (ж2)

Цепочка и браслет из дубайского золота с оригинальным плетением Длина: Цепочка от 40 до 60 см. Д…

В архиве Товар продан

Набор цепь+браслет «Афина» 0,8 см. (ж3)

Набор из цепочки и браслет из дубайского золота с оригинальным плетением Длина: от 40 до 60 см. Р…

В архиве Товар продан

Набор цепь+браслет «Gold Fish» 1,4 см (Ж2)

Необыкновенный набор из дубайского золота «Gold Fish». В набор входят браслет и цепочка Цепочка : Ш…

В архиве Товар продан

Набор цепь+браслет «Gold Fish» 1,0 см (Ж2)

Необыкновенный набор из дубайского золота «Gold Fish». В набор входят браслет и цепочка Цепочка : Д…

В архиве Товар продан

Набор цепь+браслет 0,5 см. «Двойная» (ж4)

Стильный набор из дубайского золота.В набор входит цепочка и браслет. Ширина: 0,5 см. Длину брасл…

В архиве Товар продан

Набор цепь+браслет «Афина» 0,4 см.

(к1)

Набор из цепочки и браслет из дубайского золота с оригинальным плетением Цепочка: Длина: от 40 до 6…

В архиве Товар продан

Набор «Императрица» 0,3-0,4 (Ж3)

Шикарный комплект из дубайского золота. Длина цепочки: от 40 до 60см Длина браслета: от 15 до 25см…

В архиве Товар продан

Набор «Императрица» 0,5-0,6 см. (ж4)

Шикарный набор из дубайского золота для настоящих цариц! Ширина: 0,5-0,6 см

В архиве Товар продан

630 р

1 заказ

Набор из жемчуга «Невеста» 0,5 см. (Ж1)

Нежный белоснежный набор из дубайского золота. Камень :Жемчуг Цепь: Ширина 0,5 см. Браслет : Ши…

В архиве Товар продан

Набор «Танец жемчуга» (Ж1)

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

В архиве Товар продан

Набор цепь+браслет «Love» ребристый (к1)

Цепочка и браслет из дубайского золота с необычным плетением в виде сердец Ширина цепи и браслета:…

В архиве Товар продан

Набор цепь+браслет «Афродита» 0,4 см. (к1)

Цепочка и браслет из дубайского золота с оригинальным плетением Ширина: 0,4 см. Длина браслета от…

В архиве Товар продан

Набор «Солнечная нить» (Ж4)

Сияющий набор из дубайского золота. Плетение «жгут». В набор входят цепь и браслет. Ширина цепи: 0…

В архиве Товар продан

Набор «Шикарная Мадонна» (Ж4)

Восхитительный набор из дубайского золота. В набор входят цепь и браслет Ширина цепи: 0,7-0,8 см. Д…

В архиве Товар продан

Набор «Жемчужное счастье» (Ж1)

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

В архиве Товар продан

Набор «Блеск жемчуга» (Ж1)

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

В архиве Товар продан

Набор «Магдалена» (Ж1)

Роскошный набор из дубайского золота. В набор входят колье, браслет и серьги. камни: кубический цир…

В архиве Товар продан

Следующая коллекция

Кулон + цепь

Доставка 20 марта

Каталог товаров для женщин во ВладивостокеЖенские аксессуары и украшения во ВладивостокеКупить бижутерию

Все, что вам нужно знать о написании эффективных комментариев в вашем коде | by Kurtis Pykes

Это так же важно, как написать исходный код

Опубликовано в

9 мин чтения

3 мая 2022 г.

Photo by Thomas Bormans on Unsp lash

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

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

«Программы должны быть написаны для того, чтобы их могли читать люди, и лишь случайно для того, чтобы машины могли выполнять их».
— Гарольд Абельсон

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

  Оглавление  
 -  5 неписаных правил о комментариях в Python  
 - Правило №1 Комментарии представляют собой полные предложения как код он комментирует 
 - Правило №4 Ставьте пробел после # 
 - Правило №5 Ссылки не заменяют пояснения 
 -  Различные типы комментариев    
 - Встроенные комментарии 
 - Поясняющие комментарии 
 - Обобщающие комментарии 
 - Юридические комментарии 
 - Комментарии тега кода

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

 # Это однострочный комментарий. # Это пример 
 # нескольких однострочных 
 # комментариев, которые составляют 
 # многострочный комментарий."""Это пример 
 многострочных строк с тройными кавычками 
, которые составляют 
 многострочный комментарий. comment."""

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

Вы можете встретить людей, которые считают комментарии второстепенными или говорят вам, что «комментарии не важны», игнорируйте их. Идите и прочитайте исходный код любой популярной библиотеки, чтобы увидеть их значение. Комментарии, безусловно, необходимы, если вы хотите, чтобы ваш код был 1) более читабельным и 2) более профессиональным.

Однако есть 5 золотых правил, которым нужно следовать, чтобы писать эффективный код.

Правило №1 Комментарии — это полные предложения

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

 # данные из каталога поездов  <-- Нехорошо  
 data = load_data()# Загрузить данные из каталога поездов.  <-- Хорошо  
 data = load_data()

Правило № 2 Комментарии должны соответствовать ограничениям строк

Руководство по стилю Python, PEP 8, было создано, чтобы служить набором лучших практик для программирования на Python. В одном из рекомендаций предлагается ограничить длину строки 79 символами: это руководство применимо как к исходному коду, так и к комментариям.

 # Этот комментарий настолько длинный, что не помещается даже на одной строке в ячейках кода, предоставленных средой.  <-- Плохо  # Этот комментарий намного короче и в пределах допустимого.  <-- Хорошо

Программисты все время нарушают предложенный PEP 8 предел строки, и это нормально — в конце концов, это всего лишь руководство. Но ваши комментарии по-прежнему должны соответствовать тому ограничению строк, которое вы согласовали со своей командой [или сами с собой, если вы работаете в одиночку].

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

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

  def  example_function(): 
 # Произвести случайное вычисление.   <-- Плохо  
 random = 24 + 4 
  return  random  def  example_function(): 
 # Выполнить случайный расчет.  <-- Хорошо  
 random = 24 + 4 
  return  random

Правило №4 Ставьте пробел после #

Пробел после # улучшает читабельность.

 #Это допустимо, но не легко читается.  <-- Плохо  
 # Это корректно и легко читается.  <-- Хорошо

Правило №5 Ссылки не заменяют объяснения

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

Примечание : Приведенный ниже пример кода является фрагментом кода Scikit-learn .

  # Плохо  
  def  _check_input_parameters(  self  , X, y, groups):  --- snip --- 
 # см. https://github.com/scikit-learn/scikit - Learn/issues/15149 
  если нет  _yields_constant_splits(self._checked_cv_orig): 
  поднять ValueError  ( 
 "Параметр cv должен давать согласованные сгибы" 
 "вызывает функцию split(). Установите для параметра random_state значение int или" 
 " установите shuffle=False." 
 ) 
 --- snip ---  # Хорошо 
 def  _check_input_parameters(  self  , X, y, groups): 
  --- snip --- # Нам нужно обеспечить выполнение последовательных вызовов cv.split () yield 
 # те же разбиения: 
 # см. https://github.com/scikit-learn/scikit-learn/issues/15149  если не  _yields_constant_splits(self._checked_cv_orig): 
  поднять ValueError  ( 
 "Параметр cv должен давать согласованные свертки для " 
 "вызовов split().  Установите для его random_state значение int или" 
 " установите shuffle=False." 
 ) 
 --- snip ---

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

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

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

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

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

Давайте рассмотрим некоторые из этих методов:

Встроенные комментарии

Встроенные комментарии располагаются в конце строки кода. Есть две основные причины использовать встроенный комментарий:

#1 Если переменная была определена, но причина использования конкретного объекта неясна, вы можете использовать встроенный комментарий, чтобы обосновать свое решение.

 AGE = 18 # Возраст, с которого разрешено употребление алкоголя в Великобритании.

#2 Еще одно полезное использование встроенного комментария — уменьшение двусмысленности за счет предоставления большего контекста тому, что определяется.

 day = 3 # Дни в неделе варьируются от 0 (пн) до 6 (вс) 
 height = 1,75 # Высота указана в метрах

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

 """Код взят из моего проекта модели обнаружения мошенничества. /train_pipeline.py"""  from  config.core  import  config # type: ignore 
  from  pipe  import  Fraction_detection_pipe # type: ignore 
  from  processing.data_manager 900 22 import  load_datasets, save_pipeline # тип: игнорировать 
  from  sklearn.model_selection  import  train_test_split # type: ignore

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

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

Объясняющие комментарии

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

Например, взгляните на этот комментарий:

 число_слов *= 0,2 # Умножить количество слов на 0,2.

Приведенный выше сценарий — прекрасный пример бессмысленного комментария. Не нужно быть ученым-ракетчиком, чтобы понять, что вы умножаете number_of_words на 0,2 , поэтому нет необходимости указывать это снова в комментарии.

Вот улучшенная версия:

 number_of_words *= 0,2 # Учетная запись для каждого слова стоимостью 0,20 доллара США.

Этот комментарий позволяет лучше понять намерения программиста: теперь мы знаем, что 0,2 — это цена за слово.

Примечание : Если вы читали 7 запахов кода, о которых вы должны знать и которых следует избегать , вы должны знать, что мы могли бы еще больше улучшить этот код, опустив магическое число, назначив ему константу (т.е. PRICE_PER_WORD = 0,2 ).

Обобщающие комментарии

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

 """Это небольшая часть функциональности, извлеченная из 
 кодовой базы Scikit-learn. См.: https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/impute/_knn.py. #L262"""# Удаляет столбцы, в которых все обучающие данные имеют значение nan 
  если не  np.any(mask): 
  return  X[:, valid_mask]row_missing_idx = np. flatnonzero(mask.any(axis=1))non_missing_fix_X = np.logical_not(mask_fit_X)# Карты из индексов из X к индексам в матрице dist 
 dist_idx_map = np.zeros(X.shape[0], dtype=  int  ) dist_idx_map[row_missing_idx] = np.arange(row_missing_idx.shape[0])

Сводные комментарии просто кайф -level обзор того, что происходит в коде. Размещение их точками в разных местах вашей кодовой базы позволяет товарищам по команде [и вам в будущем] быстро просмотреть код для лучшего понимания — это также показывает, что вы знаете, как работает код.

Юридические комментарии

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

Вот пример из исходного файла _knn.py Scikit-learn:

 # Авторы: Ашим Бхаттараи  
 # Томас Дж.  Фан  
 # Лицензия: пункт BSD 3

Комментарии к тегу кода

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

Наиболее часто встречающийся тег — TODO.

 """  Это пример комментария тега кода в базе кода 
 Scikit-learn. Полный код можно найти здесь: 
   https://github.com/scikit-learn/scikit-learn/ blob/main/sklearn/metrics/pairwise.py  """  def pairwise_distances_argmin_min( 
 X, Y, *, axis=1, metric="euclidean", metric_kwargs=None 
 ): 
 --- отрезать --- 
  else  : 
 # TODO: один раз PairwiseDistancesArgKmin поддерживает разреженные входные 
 # матрицы и 32-битные, нам больше не нужно отступать к 
 #pairwise_distances_chunked. Отключите проверку на 
 # конечность, потому что это дорого и поскольку массив 
 # уже проверен.  
 --- snip ---

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

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

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

Какие комментарии я пропустил? Оставить комментарий.

Спасибо за внимание.

Свяжитесь со мной:
LinkedIn
Twitter
Instagram

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

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

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

Получать электронное письмо всякий раз, когда Куртис Пайкс публикует. Зарегистрировавшись, вы создадите учетную запись Medium, если у вас ее еще нет…

kurtispykes.medium.com

Написание комментариев на Python (Руководство) — Real Python

Удалить рекламу
При чтении собственного кода
Клиент А хочет выполнить развертывание своего веб-сервиса в последнюю минуту. У вас уже сжатые сроки, поэтому вы решаете просто заставить это работать. Все эти «лишние» вещи — документация, правильные комментарии и так далее — вы добавите позже.
Приближается крайний срок, и вы развертываете службу точно в срок. Фу!
Вы делаете мысленную пометку вернуться и обновить комментарии, но прежде чем вы успеваете добавить это в свой список дел, ваш босс приходит с новым проектом, который вам нужно немедленно приступить к работе. Через несколько дней вы совершенно забыли, что должны были вернуться и должным образом прокомментировать код, который вы написали для Клиента А.
Перенесемся на шесть месяцев вперед. Клиенту А требуется исправление, созданное для той же службы, чтобы соответствовать некоторым новым требованиям. Это ваша работа, поддерживать его, так как вы были тем, кто построил его в первую очередь. Вы открываете текстовый редактор и…
Что ты вообще написал?!
Вы часами копаетесь в своем старом коде, но полностью теряетесь в беспорядке. Вы были в такой спешке в то время, что вы не правильно назвали свои переменные или даже не настроили свои функции в правильном потоке управления. Хуже всего то, что у вас нет комментариев в сценарии, чтобы сказать вам, что к чему!
Разработчики постоянно забывают, что делает их собственный код, особенно если он был написан давным-давно или под большим давлением. Когда крайний срок быстро приближается, а часы, проведенные перед компьютером, привели к воспаленным глазам и судорогам в руках, это давление может отразиться в виде кода, который стал более беспорядочным, чем обычно.
После отправки проекта многие разработчики просто слишком устали, чтобы вернуться и прокомментировать свой код. Когда придет время вернуться к нему позже, они могут часами пытаться проанализировать то, что они написали.
Написание комментариев по ходу работы — отличный способ предотвратить описанный выше сценарий. Будьте добры к будущему вам!
Когда другие читают ваш код
Представьте, что вы единственный разработчик, работающий над небольшим проектом Django. Вы довольно хорошо понимаете свой собственный код, поэтому не склонны использовать комментарии или любую другую документацию, и вам это нравится. Комментарии требуют времени на написание и поддержание, и вы просто не видите смысла.
Единственная проблема заключается в том, что к концу года ваш «маленький проект Django» превратился в проект «20 000 строк кода», и ваш руководитель привлекает дополнительных разработчиков для его поддержки.
Новые разработчики усердно работают, чтобы быстро набрать скорость, но уже через несколько дней совместной работы вы понимаете, что у них возникли проблемы. Вы использовали несколько причудливых имен переменных и написали с очень лаконичным синтаксисом. Новые сотрудники тратят много времени на просмотр кода строка за строкой, пытаясь понять, как все это работает. Пройдет несколько дней, прежде чем они смогут даже помочь вам сохранить его!
Использование комментариев в коде может помочь другим разработчикам в подобных ситуациях. Комментарии помогают другим разработчикам просмотреть ваш код и очень быстро понять, как он работает. Вы можете помочь обеспечить плавный переход, решив комментировать свой код с самого начала проекта.
Теперь, когда вы понимаете, почему так важно комментировать свой код, давайте рассмотрим некоторые основы, чтобы вы знали, как это делать правильно.
Комментарии предназначены для разработчиков. Они описывают части кода там, где это необходимо для облегчения понимания программистами, в том числе и вами.
Чтобы написать комментарий на Python, просто поставьте решетку # перед желаемым комментарием:
# Это комментарий
Python игнорирует все после знака решетки и до конца строки. Вы можете вставить их в любое место вашего кода, даже в другой код:
print("Это запустится.") # Это не запустится
Когда вы запустите приведенный выше код, вы увидите только вывод Это будет выполнено. Все остальное игнорируется.
Комментарии должны быть короткими, приятными и по существу. В то время как PEP 8 рекомендует хранить код на уровне 79 или меньше символов в строке, он предлагает максимум 72 символа для встроенных комментариев и строк документации. Если ваш комментарий приближается к этой длине или превышает ее, вам нужно распределить ее по нескольким строкам.
Удалить рекламу
К сожалению, в Python нет возможности писать многострочные комментарии, как в таких языках, как C, Java и Go:
# Значит нельзя просто сделай это в питоне
В приведенном выше примере первая строка будет проигнорирована программой, но остальные строки вызовут синтаксическую ошибку.
Напротив, такой язык, как Java, позволит вам довольно легко распределить комментарий по нескольким строкам:
/* Вы можете легко написать многострочный комментарии в Java */
Все, что находится между /* и */ , игнорируется программой.
Хотя в Python нет встроенной функции многострочных комментариев, вы можете создавать многострочные комментарии в Python. Есть два простых способа сделать это.
Первый способ — просто нажать клавишу return после каждой строки, добавить новую решетку и продолжить свой комментарий оттуда:
определение multiline_example(): # Это довольно хороший пример # того, как вы можете распространять комментарии # по нескольким строкам в Python
Каждая строка, начинающаяся с решётки, будет игнорироваться программой.
Вы также можете использовать многострочные строки, заключив свой комментарий в тройные кавычки:
""" Если я действительно ненавижу нажимать `enter` и набрав все эти решётки, я мог бы просто сделай это вместо """
Это похоже на многострочные комментарии в Java, где все, что заключено в тройные кавычки, будет функционировать как комментарий.
Хотя это дает вам многострочную функциональность, технически это не комментарий. Это строка, которая не назначена ни одной переменной, поэтому ваша программа не вызывает ее и не ссылается на нее. Тем не менее, поскольку он будет проигнорирован во время выполнения и не появится в байт-коде, он может эффективно действовать как комментарий. (Вы можете взглянуть на эту статью, чтобы убедиться, что эти строки не будут отображаться в байт-коде.)
Однако будьте осторожны при размещении этих многострочных «комментариев». В зависимости от того, где они находятся в вашей программе, они могут превратиться в строки документации, которые представляют собой части документации, связанные с функцией или методом. Если вы поместите одного из этих плохих парней сразу после определения функции, то то, что вы намеревались сделать комментарием, станет связанным с этим объектом.
Будьте осторожны при их использовании, а если сомневаетесь, просто ставьте решетку на каждой последующей строке. Если вам интересно узнать больше о строках документации и о том, как связать их с модулями, классами и т. п., ознакомьтесь с нашим руководством по документированию кода Python.
Может быть утомительно вводить все эти решётки каждый раз, когда вам нужно добавить комментарий. Итак, что вы можете сделать, чтобы немного ускорить процесс? Вот несколько приемов, которые помогут вам при комментировании.
Первое, что вы можете сделать, это использовать несколько курсоров. Это именно то, на что это похоже: размещение более одного курсора на экране для выполнения задачи. Просто нажмите и удерживайте клавишу Ctrl или Cmd , щелкая левой кнопкой мыши, и вы должны увидеть мигающие линии на экране:
Это наиболее эффективно, когда вам нужно прокомментировать одно и то же в нескольких местах.
Что делать, если у вас есть длинный фрагмент текста, который необходимо закомментировать? Скажем, вы не хотите, чтобы определенная функция выполнялась для проверки наличия ошибки. Щелчок по каждой строке, чтобы прокомментировать ее, может занять много времени! В этих случаях вы захотите вместо этого переключить комментарии. Просто выберите нужный код и нажмите Ctrl + / на ПК или Cmd + / на Mac:
Весь выделенный текст будет начинаться с решётки и игнорироваться программой.
Если ваши комментарии становятся слишком громоздкими или комментарии в сценарии, который вы читаете, очень длинные, то ваш текстовый редактор может дать вам возможность свернуть их, используя маленькую стрелку вниз слева:
Просто щелкните стрелку, чтобы скрыть комментарии. Это лучше всего работает с длинными комментариями, распределенными по нескольким строкам, или строками документации, которые занимают большую часть начала программы.
Сочетание этих советов сделает комментирование вашего кода быстрым, легким и безболезненным!
Удалить рекламу
Хотя хорошо знать, как писать комментарии на Python, не менее важно убедиться, что ваши комментарии удобочитаемы и понятны.
Взгляните на эти советы, которые помогут вам писать комментарии, которые действительно поддерживают ваш код.
При написании кода для себя
Вы можете облегчить себе жизнь, правильно комментируя собственный код. Даже если больше никто этого не увидит, вы это увидите, и этого достаточно, чтобы все исправить. В конце концов, вы разработчик, поэтому ваш код также должен быть легким для понимания.
Чрезвычайно полезный способ использования комментариев для себя — это схема вашего кода. Если вы не уверены, как получится ваша программа, вы можете использовать комментарии как способ следить за тем, что осталось сделать, или даже как способ отслеживания высокоуровневого потока вашей программы. Например, используйте комментарии, чтобы описать функцию в псевдокоде:
из коллекций импортировать defaultdict def get_top_cities (цены): top_cities = defaultdict (целое число) # Для каждого ценового диапазона # Получить поиск города по этой цене # Подсчитать, сколько раз город обыскивался # Возьмите 3 лучших города и добавьте в словарь вернуть словарь (top_cities)
Эти комментарии планируют get_top_cities() . Как только вы точно знаете, что вы хотите, чтобы ваша функция делала, вы можете работать над переводом этого в код.
Подобные комментарии помогут держать все в голове. По мере прохождения программы вы будете знать, что осталось сделать, чтобы получить полностью функциональный сценарий. После «перевода» комментариев в код не забудьте удалить все комментарии, которые стали излишними, чтобы ваш код оставался четким и чистым.
Вы также можете использовать комментарии как часть процесса отладки. Закомментируйте старый код и посмотрите, как это повлияет на результат. Если вы согласны с изменением, то не оставляйте код в своей программе закомментированным, так как это снижает читабельность. Удалите его и используйте контроль версий, если вам нужно вернуть его.
Наконец, используйте комментарии для определения сложных частей собственного кода. Если вы отложите проект и вернетесь к нему спустя месяцы или годы, вы потратите много времени, пытаясь заново ознакомиться с написанным. В случае, если вы забудете, что делает ваш собственный код, сделайте одолжение Future You и отметьте его, чтобы позже было легче вернуться к скорости.
При написании кода для других
Людям нравится пролистывать текст и перескакивать туда-сюда, и чтение кода не исключение. Единственный раз, когда вы, вероятно, будете читать код построчно, это когда он не работает, и вам нужно выяснить, что происходит.
В большинстве других случаев вам потребуется беглый взгляд на определения переменных и функций, чтобы понять суть. Наличие комментариев, объясняющих происходящее на простом английском языке, может действительно помочь разработчику в этой ситуации.
Будьте добры к своим коллегам-разработчикам и используйте комментарии, чтобы помочь им просмотреть ваш код. Встроенные комментарии следует использовать с осторожностью, чтобы прояснить фрагменты кода, которые сами по себе неочевидны. (Конечно, вашим главным приоритетом должно быть то, чтобы ваш код работал сам по себе, но в этом отношении могут быть полезны встроенные комментарии. )
Если у вас есть сложный метод или функция, название которой не совсем понятно, вы можете включить короткий комментарий после строки def , чтобы пролить свет:
определение сложных_функций: # Эта функция делает что-то сложное
Это может помочь другим разработчикам, просматривающим ваш код, понять, что делает функция.
Для любых общедоступных функций вам потребуется включить связанную строку документации, независимо от того, сложная она или нет:
def sparsity_ratio (x: np.array) -> float: """Вернуть поплавок Процент значений в массиве, равных нулю или NaN """
Эта строка станет .__doc__ атрибут вашей функции и будет официально связан с этим конкретным методом. Руководство по цепочке документации PEP 257 поможет вам структурировать строку документации. Это набор соглашений, которые разработчики обычно используют при структурировании строк документации.
В рекомендациях PEP 257 также есть соглашения для многострочных строк документации. Эти строки документации появляются прямо в верхней части файла и содержат общий обзор всего скрипта и того, что он должен делать:
.
# --*- кодировка: utf-8 --*- """Строка документации на уровне модуля Обратите внимание на комментарий над строкой документации, указывающий кодировку. Строки документации появляются в байт-коде, поэтому вы можете получить к ним доступ через атрибут ``__doc__``. Это также то, что вы увидите, если позвоните help() для модуля или любого другого объекта Python. """
Строка документации на уровне модуля, подобная этой, будет содержать любую относящуюся к делу или необходимую информацию для читающего ее разработчика. При написании рекомендуется перечислить все классы, исключения и функции, а также краткое описание каждого из них.
Удалить рекламу
Так же, как существуют стандарты для написания комментариев Python, есть несколько типов комментариев, которые не ведут к коду Pythonic. Здесь только несколько.
Ваши комментарии должны быть D.R.Y. Аббревиатура расшифровывается как принцип программирования «Не повторяйся». Это означает, что в вашем коде не должно быть избыточности. Вам не нужно комментировать фрагмент кода, который достаточно объясняет сам себя, например этот:
.
return a # Возвращает a
Мы ясно видим, что возвращается a , поэтому нет необходимости явно указывать это в комментарии. Это делает комментарии W.E.T., означающие, что вы «все написали дважды». (Или, для более циничного, «впустую потратили все время».)
В.Э.Т. комментарии могут быть простой ошибкой, особенно если вы использовали комментарии для планирования кода перед его написанием. Но как только код заработает, обязательно вернитесь и удалите комментарии, которые стали ненужными.
Комментарии могут быть признаком «запаха кода», то есть всем, что указывает на наличие более глубокой проблемы с вашим кодом. Запахи кода пытаются замаскировать основные проблемы программы, а комментарии — один из способов попытаться скрыть эти проблемы. Комментарии должны поддерживать ваш код, а не пытаться его объяснить. Если ваш код написан плохо, никакие комментарии не исправят его.
Возьмем простой пример:
# Словарь семей, живущих в каждом городе мой дикт = { «Мидтаун»: [«Пауэлл», «Брэнтли», «Янг»], «Норкросс»: [«Монтгомери»], «Экворт»: [] } деф (дикт): # Для каждого города для p в словаре: # Если в городе нет семей если не mydict[p]: # Сказать, что семей нет печатать("Нет").
Этот код довольно непослушный. Перед каждой строкой есть комментарий, объясняющий, что делает код. Этот скрипт можно было бы упростить, назначив очевидные имена переменным, функциям и коллекциям, например:0005
семей_по_городу = { «Мидтаун»: [«Пауэлл», «Брэнтли», «Янг»], «Норкросс»: [«Монтгомери»], «Экворт»: [], } определение no_families (города): для города в городах: если не family_by_city[город]: print(f"Нет семей в {городе}. ")
Используя очевидные соглашения об именах, мы смогли удалить все ненужные комментарии и сократить длину кода!
Ваши комментарии редко должны быть длиннее поддерживаемого ими кода. Если вы тратите слишком много времени на объяснение того, что вы сделали, вам нужно вернуться назад и провести рефакторинг, чтобы сделать ваш код более ясным и лаконичным.
Это то, что может возникнуть при работе в команде разработчиков. Когда несколько человек работают над одним и тем же кодом, другие будут входить и проверять то, что вы написали, и вносить изменения. Время от времени вы можете встретить кого-то, кто посмеет написать комментарий, подобный этому:
.
# Поместите это сюда, чтобы исправить тупую ошибку Райана.
Честно говоря, лучше этого не делать. Ничего страшного, если это код вашего друга, и вы уверены, что он не обидится на него. Вы никогда не знаете, что может быть отправлено в производство, и как это будет выглядеть, если вы случайно оставили там этот комментарий, и клиент обнаружил его в будущем? Вы профессионал, и использование грубых слов в комментариях — не способ показать это.
Самый простой способ начать писать больше Pythonic-комментариев — это просто сделать это!
Начните писать комментарии для себя в собственном коде. Возьмите за правило включать простые комментарии там, где это необходимо. Добавьте немного ясности в сложные функции и поместите строку документации в начало всех ваших скриптов.
Еще один хороший способ попрактиковаться — вернуться и просмотреть старый код, который вы написали. Посмотрите, где что-то может не иметь смысла, и очистите код. Если он все еще нуждается в дополнительной поддержке, добавьте быстрый комментарий, чтобы прояснить цель кода.
Это особенно хорошая идея, если ваш код размещен на GitHub и люди разветвляют ваш репозиторий. Помогите им начать работу, проведя их через то, что вы уже сделали.
Вы также можете отблагодарить сообщество, комментируя код других людей. Если вы загрузили что-то с GitHub и у вас возникли проблемы с его сортировкой, добавляйте комментарии по мере того, как вы понимаете, что делает каждый фрагмент кода.
«Подпишите» свой комментарий своими инициалами и датой, а затем отправьте свои изменения в виде запроса на вытягивание. Если ваши изменения будут объединены, вы можете помочь десяткам, если не сотням таких же разработчиков, как вы, получить преимущество в своем следующем проекте.
Удалить рекламу
Умение хорошо комментировать — ценный инструмент. Вы не только научитесь писать более четко и лаконично в целом, но и, без сомнения, получите более глубокое понимание Python.
Умение писать комментарии на Python может облегчить жизнь всем разработчикам, включая вас самих! Они могут помочь другим разработчикам освоить то, что делает ваш код, и помочь вам заново ознакомиться с вашим собственным старым кодом.
Заметив, что вы используете комментарии для поддержки плохо написанного кода, вы сможете вернуться и изменить свой код, чтобы сделать его более надежным. Комментирование ранее написанного кода, своего собственного или кода другого разработчика, — отличный способ попрактиковаться в написании четких комментариев в Python.