PSA: Кодируйте разборчиво или будьте ненавидимы

Код читается чаще, чем пишется

Это публичное объявление для всех специалистов по данным. Пожалуйста, пишите разборчиво. Если бы не здравомыслие ваших сотрудников, то для вашего собственного здравомыслия через x месяцев / лет.

Личный анекдот

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

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

«мы можем сделать это, мы можем сделать это, мы можем сделать это».

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

Конечно, у старших докторов наук, оценивавших наш код, было намного хуже. Наша когорта из 12–15 студентов магистратуры выполняла домашнее задание по программированию, которое иногда давало 50+ страниц результатов каждое ... еженедельно. Я до сих пор помню нашего ТА и его слезы. Я слышал, он все еще ходит по коридорам в поисках кого-нибудь, кто поможет ему оценить нашу работу.

Главное

В этом нет ничего хуже, чем видеть вложенность двузначных подзапросов HiveQL / SQL и не соблюдать максимумы строковых символов¹. Я чуть не утонул в рубиновых реках крови, текущих из моих налитых кровью глаз, когда читал такой код.

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

четкий узор относительно белого пятна
отступ?

Хорошее кодирование обеспечивает непрерывность продукта. Документация еще лучше. Хотя документация не увлекательна и не всегда вознаграждается, она позволяет кому-то другому продолжить вашу работу и получать от нее удовольствие. В результате получается лучшее программное обеспечение, которое легче поддерживать.

Хорошее кодирование имеет нюансы: может быть слишком много или слишком мало чего-либо, например, белого интервала. Вот пара примеров, которые подчеркивают сложные нюансы хорошего кодирования:

Пример: слишком мало белого пространства

Думаю, этих картинок достаточно.

Пример: слишком много белого пространства

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

Пример: нет универсального правила

Иногда нет единого правила, принятого для нескольких языков. Например, такая простая вещь, как максимальное количество символов в строке, имеет разные стандарты для разных языков:

Заключение

Согласованность стиля - первостепенная цель проектов по написанию кода. Не имеет особого значения, каким конкретным соглашениям следует проект, если он согласован. Достаточно сложно понять большие системы без необходимости иметь дело с различными схемами отступов, соглашениями об именах и идиомами для разных разделов кода. Гвидо Ван Россум, автор Python, говорит об этом лучше всего:

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

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

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

Вот несколько руководств по стилю для наиболее часто используемых языков от специалистов по данным:

Python