Этот учебник, взятый из моей предстоящей книги программирования «от одного до нуля» (Nostarch, 2021), покажет вам, как написать отличные комментарии. В то время как большинство онлайн-учебных пособий сосредоточены на списке комментирующих советов, мы погрузимся глубже в мясе, исследуя основные причины для общно рекомендуемых принципов комментирования. Итак, давайте начнем!
Код для людей не машин
«Любой дурак может написать код, который может понять компьютер. Хорошие программисты пишут код, которые могут понять, что люди могут понять». – Мартин Фаулен
Основная цель исходного кода состоит в том, чтобы определить, какие машины должны делать и как это сделать.
Тем не менее, если это было единственным критерием, вы бы использовали язык машины низкого уровня, такой как ассемблер для достижения этой цели, потому что это самый выразительный и самый мощный язык.
Целью высокого уровня языков программирования, таких как Python, заключается в том, чтобы помочь людям писать лучший код и сделать это быстрее. Наш следующий принцип для чистого кода – постоянно напоминать себе, что вы пишете код для других людей, а не для машин.
Если ваш код будет иметь какое-либо влияние в реальном мире, Это будет прочитать несколько раз или программист, который занимает ваше место Если вы перестанете работать на базе кода. Всегда предполагайте, что ваш исходный код будет прочитан другими людьми. Что вы можете сделать, чтобы облегчить свою работу? Или, чтобы положить его прямо: Что вы можете сделать, чтобы смягчить негативные эмоции, которые они испытывают против первоначального программиста кодового основания их работать? Код для людей не машин!
Сократить время для понимания
Если вы пишете код для людей, а не машин, вам нужно использовать комментарии, чтобы помочь читателям вашего кода понять его лучше и быстрее. Короткий комментарий может значительно сократить время, чтобы познавать значение базы кода. Рассмотрим следующий код примера:
import re
text = '''
Ha! let me see her: out, alas! he's cold:
Her blood is settled, and her joints are stiff;
Life and these lips have long been separated:
Death lies on her like an untimely frost
Upon the sweetest flower of all the field.
'''
f_words = re.findall('\\bf\w+\\b', text)
print(f_words)
l_words = re.findall('\\bl\w+\\b', text)
print(l_words)
'''
OUTPUT:
['frost', 'flower', 'field']
['let', 'lips', 'long', 'lies', 'like']
'''
Плохой код примера без комментариев.
Предыдущий кодовый фрагмент анализирует короткий текстовый фрагмент из Шекспира Ромео и Джульетта Использование Регулярные выражения Отказ Если вы не очень знакомы с регулярными выражениями, вы, вероятно, боретесь по понимаете, что делает код. Даже имеющие имена имена переменной не помогают. Давайте посмотрим, может ли несколько комментариев разрешить вашу путаницу!
import re
text = '''
Ha! let me see her: out, alas! he's cold:
Her blood is settled, and her joints are stiff;
Life and these lips have long been separated:
Death lies on her like an untimely frost
Upon the sweetest flower of all the field.
'''
# Find all words starting with character 'f'
f_words = re.findall('\\bf\w+\\b', text)
print(f_words)
# Find all words starting with character 'l'
l_words = re.findall('\\bl\w+\\b', text)
print(l_words)
'''
OUTPUT:
['frost', 'flower', 'field']
['let', 'lips', 'long', 'lies', 'like']
'''
Хороший пример кода с комментариями.
Две короткие комментарии значительно помогают понять Шаблоны регулярного выражения '\\ bf \ w + \\ b' и '\\ bl \ w + \\ b' Отказ Хотя я не буду глубоко погрузиться в регулярные выражения здесь, пример показывает, как комментарии могут помочь вам получить грубое понимание кода других людей без понимания каждого и каждого синтаксического сахара. Для вводных учебных пособий в мощные технологии регулярные выражения, проверьте наши две технические книги Python One-listers и Самый умный способ выучить регулярные выражения Python Отказ
Вы эксперт – поделитесь своей мудростью!
Полезные комментарии Придайте проблеск в свое мышление – как вы написали код, вы обладаете ценным пониманием его только на немногие люди. Не пропустите поделиться с другими людьми! Комментарии могут быть очень полезны для «абстрактных» по блокам кода. Например, если у вас есть пять строк кода, касающихся обновления информации о клиентах в базе данных, добавьте короткий комментарий перед блоком, чтобы объяснить это. Это поможет читателю получить быстрый обзор вашего кода и ускоряет их и ваше «время загрузки кода». Вы можете найти пример такого экземпляра следующего:
# Process next order order = get_next_order() user = order.get_user() database.update_user(user) database.update_product(order.get_order()) # Ship order & confirm customer logistics.ship(order, user.get_address()) user.send_confirmation()
Комментарий Блоки помогают получить обзор кода.
Код иллюстрирует, как интернет-магазин завершает заказ клиента на двух этапах высокого уровня: (1) Обработка следующего заказа и (2) Доставка доставки. Комментарии помогут вам понять цель кода за несколько секунд без необходимости смотреть на каждый отдельный вызов метода.
Комментарии как предупреждения!
Вы также можете использовать комментарии как предупреждение потенциально нежелательных последствий. Это увеличивает уровень внимания программатора, работающего с вашим кодом. Следующий код показывает такой пример, где программисты предупреждают перед вызовом функции Ship_yacht () Это будет вступить в действие дорогой яхтой для клиента.
##########################################################
# WARNING #
# EXECUTING THIS FUNCTION WILL SHIP A $1,569,420 YACHT!! #
##########################################################
def ship_yacht(customer):
database.update(customer.get_address())
logistics.ship_yacht(customer.get_address())
logistics.send_confirmation(customer)
Комментарии как предупреждения.
Есть много способов использования комментариев полезным способом. Комментарии всегда есть для человеческого читателя, поэтому всегда имейте в виду, что вы пишете код для людей, а не машин!
Избегайте ненужных комментариев
Не все комментарии помогают читателям лучше понимать код лучше. На самом деле, есть много случаев, когда комментарии снижают ясность и путают читателей данной базы кода. Если ваша цель – написать чистый код, вы должны не только использовать ценные комментарии, но и избежать ненужных комментариев. Но какие ненужные комментарии? Давайте погрузимся в те, которые следуют.
Во время своего времени как исследователь компьютерных наук, многие из моих студентов старшего уровня подробно описали меня, как прошли их интервью на различных компаниях. Очень опытный студент успешно подал заявку на работу в Google. Он сказал мне, что Google Headheunters – они обычно инженеры Google – критиковали свой стиль кода, потому что он добавил слишком много ненужных комментариев. Эти типы комментариев так называются «Код запахов», – очень быстро выяснит, что вы Новичок, промежуточный или экспертный кодер сам. Ненужные комментарии делают это очень очевидно. Но какие ненужные комментарии? В большинстве случаев они добавляют уровень избыточности к коду. Отличный кодер будет использовать значимые имена переменной ( Принцип : Используйте правильные имена ), поэтому код часто становится самоочередным – по крайней мере, по сравнению с кодом, который не использует правильные имена. Давайте пересмотрим фрагмент кода осмысленными именами переменной.
investments = 10000
yearly_return = 0.1
years = 10
for year in range(years):
print(investments * (1 + yearly_return)**year)
Комментариев не нужна.
Код рассчитывает вашу кумулятивную доходность инвестиций в течение десяти лет, принимая доходность 10%. Теперь давайте добавим некоторые ненужные комментарии!
investments = 10000 # your investments, change if needed
yearly_return = 0.1 # annual return (e.g., 0.1 --> 10%)
years = 10 # number of years to compound
# Go over each year
for year in range(years):
# Print value of your investment in current year
print(investments * (1 + yearly_return)**year)
Ненужные комментарии.
Все комментарии в предыдущем фрагменте кода являются избыточными. Некоторые из них были бы полезны, если вы выбрали менее значимые имена переменной, такие как х , y или z Отказ Но объяснение переменной имени ждать_return С помощью комментариев не предоставляет никакого относительного значения. Спасибо, это уменьшает ценность, потому что он добавляет ненужный беспорядок в код. Дополнительный беспорядок делает ваш код менее читаемым и менее лаконичным. Есть несколько правил, которые могут помочь вам избежать ненужных комментариев – хотя лучшее правило – использовать ваш здравый смысл, чтобы определить, действительно ли комментарий улучшает читаемость вашего кода.
Код запахов – отрицательные комментирующие принципы
- Не используйте встроенные комментарии. У них мало ценности и может быть полностью избежать, выбирая значимые имена переменной.
- Не будь избыточным. Избыточность является врагом ясности – это также проводит комментарии!
- Не добавляйте очевидные комментарии. Вы можете увидеть очевидный комментарий в предыдущем фрагменте кода непосредственно перед для петли утверждение. Любой кодер знает
дляпетля, так какая дополнительная стоимость вы предоставляете комментарий# Перейти каждый годКогда для петли уже говорится? За год в диапазоне (годы)?Не прокомментируйте код. - Если вы программисты, это очень вероятно, что вы виновны в этом. Мы программистым часто висят на наших любимых фрагментов кода, даже если мы уже (неохотно) решили удалить их. Застенчивый подход к удалению ненужного кода – это прокомментировать его. Тем не менее, прокомментированный код – это убийца читаемости, и вы должны избегать его на всех затратах, если вы хотите написать чистый код. Вместо того, чтобы комментировать ненужный код, смело удалить его. Для вашего разума вы должны использовать инструмент истории версий, такой как GIT, который позволяет вам получить любой старый фрагмент кода, если вам это нужно.
Многие языки программирования, такие как Python, поставляются с функциональностью документации, которая позволяет вам описать цель каждой функции, метода и класса в вашем коде. Если вы тщательно выбрали уровень абстракции каждую функцию ( принцип одной ответственности ), часто достаточно использовать сборку в функциональности документации, а не комментарию, чтобы описать, что делает ваш код. Это во многом удаляет необходимость дополнительных комментариев в вашем коде.
Вы хотите развивать навыки Хорошо округлый Python Professional То же оплачивается в процессе? Станьте питоном фрилансером и закажите свою книгу Оставляя крысиную гонку с Python На Amazon ( Kindle/Print )!
Куда пойти отсюда?
Достаточно теории, давайте познакомимся!
Чтобы стать успешным в кодировке, вам нужно выйти туда и решать реальные проблемы для реальных людей. Вот как вы можете легко стать шестифункциональным тренером. И вот как вы польские навыки, которые вам действительно нужны на практике. В конце концов, что такое использование теории обучения, что никто никогда не нуждается?
Практические проекты – это то, как вы обостряете вашу пилу в кодировке!
Вы хотите стать мастером кода, сосредоточившись на практических кодовых проектах, которые фактически зарабатывают вам деньги и решают проблемы для людей?
Затем станьте питоном независимым разработчиком! Это лучший способ приближения к задаче улучшения ваших навыков Python – даже если вы являетесь полным новичком.
Присоединяйтесь к моему бесплатным вебинаре «Как создать свой навык высокого дохода Python» и посмотреть, как я вырос на моем кодированном бизнесе в Интернете и как вы можете, слишком от комфорта вашего собственного дома.
Присоединяйтесь к свободному вебинару сейчас!
Работая в качестве исследователя в распределенных системах, доктор Кристиан Майер нашел свою любовь к учению студентов компьютерных наук.
Чтобы помочь студентам достичь более высоких уровней успеха Python, он основал сайт программирования образования Finxter.com Отказ Он автор популярной книги программирования Python One-listers (Nostarch 2020), Coauthor of Кофе-брейк Python Серия самооставленных книг, энтузиаста компьютерных наук, Фрилансера и владелец одного из лучших 10 крупнейших Питон блоги по всему миру.
Его страсти пишут, чтение и кодирование. Но его величайшая страсть состоит в том, чтобы служить стремлению кодер через Finxter и помогать им повысить свои навыки. Вы можете присоединиться к его бесплатной академии электронной почты здесь.