В Analytics мы часто увлечены новейшими алгоритмами, пакетами, рассказами и бесконечными обсуждениями R против Python. Мы часто пренебрегаем потребностью в читаемом коде.

  • Вы когда-нибудь пересматривали свой код через пару месяцев и задавались вопросом, почему вы написали этот фрагмент кода именно таким образом?
  • Прочитали ужасный код и подумали, что лучше переписать код, чем понимать нечитаемый код?
  • Видны имена наборов данных / переменных как df1, var_df2, master3, temp4, i, j и т. Д.?
if (Answer to above question == "Yes") {
“Read Further and share your experience with un-readable code”
}

Почему я выработал привычку писать читаемый код?

К счастью, у меня не было выбора. Во время моего пребывания в Capgemini мои исходные коды были нечитаемыми, и я получил массу комментариев. Основные проблемы, с которыми я столкнулся, были следующими:

  1. Огромная база кода (Клиент был одной из крупнейших сетей пиццерий в мире)
  2. Устаревшая ERP (да, я кодировал на Vb 6.0)
  3. Некоторые части не читались (было задействовано несколько команд)
  4. Взаимозависимость (изменения в одном модуле имели каскадный эффект)
  5. Гибкая методология (многие люди работают над одним и тем же файлом одновременно)

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

Профессионалы используют свои способности во благо и пишут код, понятный другим.
- Роберт К. Мартин, Чистый код: руководство по гибкому разработке программного обеспечения

Как бороться?

  • Назначение кода (краткое изложение). Обычно я предпочитаю писать краткое изложение кода. Вы можете упомянуть следующее: 1) Источник данных 2) Базовое понимание набора данных 3) Основная цель / гипотеза, которую вы проверяете 4) Любой жаргон или соответствующее описание столбца
##### Purpose for this article ######
# This is my 1st comment on any new file/project. For this story my purpose is to make the code more readable by focusing on the most ignored part of coding (Comments, Inundation, Casing)
  • Запишите предположения. Из плохих предположений получается плохой код, и отсутствие упоминания каких-либо предположений ведет к катастрофе. Допустим, вы хотите создать производную переменную «Общий стаж работы» клиента (возраст ›25 лет) на основе его« возраста ». Основываясь на вашем прошлом понимании, у вас есть предположение, что клиент обычно начинает работать в «Возрасте = 22 года», таким образом, «Общий опыт работы = Возраст - 22».
##### Assumptions for this article ######
# You have a basic understanding of how codes work and have hands-on experience in any coding language
  • Исключения. Что вы исключаете? Допустим, вы работаете над моделью склонности к ссуде на образование, вы исключите людей, которые еще не имеют права на этот курс, людей, возраст которых намного превышает возрастной сегмент. Лучше упомянуть самые важные исключения
  • Комментарии - содержательные комментарии, что делает ваша функция, каковы входные параметры? Комментарии и код должны быть синхронизированы, поэтому при изменении кода не забудьте добавить / обновить комментарий. Также удалите ненужные комментарии. Допустим, у вас есть функция, которая выполняет базовые операции с датой, при этом она принимает дату покупки и дату доставки в качестве аргумента.
#### Calculates the time to deliver in dd/mm/yyyy format. Pass date of purchase and date of delivery as arguments in mm/dd/yy format
  • Затопление. Заметили код, по которому вы не могли понять, где он начинается и где заканчивается?
##### Same Code without and with inundation ####
AbvAvgArrests <- USArrests %>% filter(Murder > mean(Murder), Rape > mean(Rape), Assault > mean(Assault))
AbvAvgArrests <- USArrests %>%                  
                 filter(Murder > mean(Murder),
                        Rape > mean(Rape), 
                        Assault > mean(Assault))
  • Релевантные имена для переменных / наборов данных / функций. Вам не следует читать код, содержащий такие переменные, как i, j, k. Назовите его в зависимости от того, что он делает. Например. Если вы просто хотите проверить работоспособность на предмет возраста, назовите его SanityAgeCheck, а не Test1. Возможно, вы захотите сохранить следующее соглашение: 1) Проверка работоспособности → SanityWhatItDoes 2) Набор временных данных → TempWhatItDoes 3) Функция → FnWhatItDoes 4) Набор исходных данных → RawWhatItDoes 5) Графики → PlotWhatItPlots и т. Д.

Вы должны назвать переменную так же осторожно, как и первенца.
- Роберт К. Мартин, Чистый код: руководство по Agile Software Craftsmanship

  • Корпус - используйте последовательный регистр, я бы не хотел readCode, который представляет собой MixtureOf несколько casing_styles
#### Types of casing styles ####
#camelCase
#PascalCase
#snake_case
  • Пробелы важны - оставляйте пробелы между разделами, это поможет при чтении кода.
  • Удалите ненужные наборы данных.

Образец кода

Советы в R studio

  • У вас есть окончательный набор данных «CustomerMaster», который содержит все соответствующие столбцы и будет использоваться для построения графиков. Теперь, если вы хотите сохранить только CustomerMaster и удалить все другие наборы данных, вы можете использовать keep (CustomerMaster, sure = TRUE) из пакета gdata.
  • CTRL + I - засыпает код
  • Чтобы создать новый комментарий раздела кода и сделать его видимым в структуре документа, прокомментируйте следующим образом.
#### Sample Comment to create new code section which can be collapsed ####

См. Снимок экрана ниже

Плюсы

  • Легко объяснить
  • Сокращение времени на передачу / документ
  • Сниженная зависимость
  • Менее подвержен ошибкам
  • Легко отлаживать, следовательно, сокращается время на устранение ошибок
  • Легко повторно использовать и изменять в зависимости от потребностей бизнеса

Минусы

  • Кропотливый
  • Вам может показаться, что это обычное занятие (поверьте, оно того стоит)
  • Не подходит, если требуется специальная подготовка и очень строгие сроки (я бы предпочел предоставить результаты, а затем сделать их читаемыми для будущего использования)

Ключевые вынос

  1. Написание читаемого кода так же важно, как написание эффективного кода, воспринимайте это как руководство пользователя (для себя и коллег)
  2. Напишите Цель / Основное резюме
  3. Напишите предположения (даже самые простые, ваш коллега может не понять ваш мыслительный процесс через 6 месяцев)
  4. Что вы исключили? (Умершие клиенты, Экстремальные значения и т. Д.)
  5. Комментарии (заменяет все остальное, сделайте это и не забудьте синхронизировать с вашим кодом по мере необходимости)
  6. Затопление (уменьшит путаницу)
  7. Соответствующее имя (укажите, что оно означает / означает)
  8. Корпус (camelCase, PascalCase, snake_case) Я предпочитаю PascalCase
  9. Пробел (оставьте несколько строк между основными разделами)
  10. Удалите нерелевантные наборы данных (вы не хотите жонглировать более чем 50 наборами данных)
  11. Да, это займет много времени, но оно того стоит. Как только вы начнете писать читаемый код, сравните код до и после редактирования.

Так что вы рассказываете о нечитаемом коде и как вы с этим справились?

Об авторе: консультант по аналитике с более чем 5-летним опытом работы с заинтересованными сторонами в разных отраслях. В настоящее время работаю бизнес-аналитиком (People Analytics), где конвертирую данные в полезные идеи.

Удачного кодирования :)