Что такое «чистый код»? Вообще говоря, чистый код – это код, который легко понять и легко изменить или поддерживать.
Поскольку код чаще читается, чем написано, практика написания чистого кода имеет решающее значение в нашей карьере.
Сегодня я делюсь несколькими советами, которые я собрал за эти годы, а также приводим несколько примеров в Python.
С учетом сказанного, эти принципы обычно должны применяться к большинству языков программирования.
TL; DR
- Быть последовательным, когда называет вещи
- Избегайте места для путаницы, когда называют вещи
- Избегайте двойных негативов
- Напишите самоэкспланирующий код
- Не злоупотреблять комментариями
1. Назовите вещи правильно
Избегайте места для путаницы
Несмотря на то, что мы самый старый трюк в книге, это самое простое правило, которое мы часто забываем. Прежде чем назвать папку, функцию или переменную, всегда спрашивает: «Если я назову это так, может ли это означать что -то еще или запутать других людей?»
Общая идея здесь состоит в том, чтобы всегда снимать место для путаницы, и называя что -либо.
# For example, you're naming a variable that represents the user's membership: # Example 1 # ^^^^^^^^^ # Don't expired = True # Do is_expired = True # Example 2 # ^^^^^^^^^ # Don't expire = '2021-04-17 03:25:37.403283' # Do expiration_date = '2021-04-17 03:25:37.403283' # OR expiration_date_string = '2021-04-17 03:25:37.403283'
Причина, почему истек менее идеальное имя, потому что истек само по себе неоднозначно. Новый разработчик, работающий над проектом, не узнает, будет ли истек это дата или логический.
Быть в соответствии с именованием
Поддержание последовательности на протяжении всего командного проекта имеет решающее значение, чтобы избежать путаницы и сомнений. Это относится к именам переменных, именами файлов, имен функций и даже структур каталогов.
Ничто не должно быть названо исключительно на основе ваших индивидуальных предпочтений. Всегда проверяйте то, что уже написали другие люди, и обсудите это, прежде чем что -либо изменить.
# For example if the existing project names a Response object as "res" already: # Existing functions # ^^^^^^^^^^^^^^^^^^ def existing_function(res, var): # Do something... pass def another_existing_function(res, var): # Do something... pass # Example 1 # ^^^^^^^^^ # Don't def your_new_function(response, var): # Do something... pass # Do def your_new_function(res, var): # Do something... pass
Дополнительные советы при выборе имен
- Переменные – существительные (т.е.
product_name). - Функции, которые делают что -то, являются глаголами (т.е.
def Compute_user_score ()). - Логические переменные или функции, возвращающие логические, являются вопросы (т.е.
def is_valid ()). - Имена должны быть описательными, но не чрезмерно словесными (т.е.
def compute_fibonacci (), а неdef compute_fibonacci_with_dynamic_programming ()).
2. Избегайте двойных негативов
” Можете ли вы убедиться, что не забудете не выключать свет позже? “
Фу. Итак, я должен выключить свет или нет? Держись, позволь мне прочитать это снова.
Давайте согласимся с тем, что двойной негатив – это просто сбивает с толку.
# Example to check if a user's membership is valid or not:
# Don't
is_invalid = False
if not is_invalid:
print("User's membership is valid!")
# Do
is_valid = True
if not is_valid:
print("User's membership is invalid!")
Если вам нужно читать его более одного раза, чтобы быть уверенным, он пахнет.
3. Напишите самоэкспланирующий код
В прошлом я помню, как мне говорили, что инженеры должны посыпать комментарии повсюду, чтобы «улучшить качество кода».
Эти времена давно прошли. Вместо этого инженеры должны писать самопроверкальный код, который имеет смысл для людей. Например, мы должны попытаться запечатлеть сложную часть логики в описательной и самопрочитаемой переменной.
# Don't write long conditionals
if meeting and (current_time > meeting.start_time) and (user.permission == 'admin' or user.permission == 'moderator') and (not meeting.is_cancelled):
print('# Do something...')
# Do capture them in many variables that reads like English
is_meeting_scheduled = meeting and not meeting.is_cancelled
has_meeting_started = current_time > meeting.start_time
has_user_permission = user.permission == 'admin' or user.permission == 'moderator'
if is_meeting_scheduled and has_meeting_started and has_user_permission:
print('# Do something...')
Не злоупотреблять комментариями
Как и сам код, комментарии тоже могут быть устаревшими.
Люди часто забывают обновлять комментарии, когда код рерсируется. Когда это произойдет, сами комментарии косвенно станут корнем путаницы.
Всякий раз, когда вы чувствуете необходимость написать комментарий, вы всегда должны переоценить код, который вы написали, чтобы увидеть, как он может быть понятен.
Примеры того, когда писать комментарии
Один из сценариев, в котором я бы рассмотрел комментарии, – это когда я должен использовать нарезку. Это просит такие вопросы, как «Почему мы делаем это так? Почему не другие индексы? ” и так далее.
# Example of getting an email returned from a 3rd party API:
# Example 1
# ^^^^^^^^^
# Do
raw_string = get_user_info()
email = raw_string.split('|', maxsplit=2)[-1] # NOTE: raw_string e.g. "Magic Rock|jerry@example.com"
Другой пример:
# Example of a function calling a random time.sleep():
# Example 2
# ^^^^^^^^^
# Don't
def create_user(user_ids):
for id in user_ids:
make_xyz_api_request(id)
time.sleep(2)
Представьте, что вы новый разработчик, который впервые смотрит на код выше.
Первое, что приходит мне в голову, это «почему мы случайным образом ждем две секунды за каждый запрос, который мы делаем?»
Оказывается, первоначальный разработчик, который написал код, просто хотел, чтобы мы ограничивали наше количество запросов, отправленных сторонним API.
# Do
def create_user(user_ids):
for id in user_ids:
make_xyz_api_request(id)
time.sleep(2) # NOTE: service 'xyz' has a rate limit of 100 requests/min, so we should slow our requests down
Всегда помещайте себя в другие туфли (то есть «как остальные интерпретируют мой код?»). Если вы нарезаете или используете определенный индекс из списка (т.е. Array [3] ), никто не знает точно, почему вы это делаете.
Как применить эти знания?
Никто не способен писать чистый код с первого дня. На самом деле все начинают с написания «плохого» или «уродливого» кода.
Как и большинство вещей в жизни, чтобы быть хорошим в чем -то, вы должны продолжать практиковать снова и снова. Вы должны поместить часы.
Помимо практики, вот вещи, которые работают для меня:
- Продолжайте задавать себе такие вопросы, как «Есть ли лучший способ написания? Это сбивает с толку для других читать? “
- Примите участие в обзорах кода.
- Исследуйте другие хорошо написанные кодовые базы. Если вам нужны примеры хорошо написанного, чистого и питонического кода, ознакомьтесь с Python Запросы библиотека.
- Поговорите с людьми, обсудить или обмениваться мнениями, и вы узнаете гораздо больше.
Последние мысли
Написание чистого кода трудно объяснить многим нетехническим людям, потому что. Для них, похоже, это практически не дает непосредственной ценности для бизнеса компании.
Написание чистого кода также занимает много дополнительного времени и внимания, и эти два фактора приводят к затратам для предприятий.
Тем не менее, в течение определенного периода времени влияние чистого кода в кодовой базе имеет решающее значение для инженеров. Благодаря более чистой кодовой базе инженеры смогут быстрее доставлять код и быстрее развернуть приложения для достижения бизнес -целей.
Вдобавок ко всему, наличие чистого кода имеет решающее значение, так что новые сотрудники или участники могли быстрее работать на земле, когда они начинаются с нового проекта.
использованная литература
Руководство по стилю Google Python
Оригинал: “https://dev.to/jerrynsh/how-to-write-clean-code-in-python-2pf3”