Программируй как писатель: секреты понятного кода

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

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

Используйте правильные названия

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

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

Ещё несколько практических советов:
- Имена булевых значений начинайте с has или is (например, isUserLoggedIn).
- Значения для названий коллекций должно употребляться во множественном числе (к примеру, Users).
- Забудьте всё, что вы знаете о наименовании. Главное, называйте переменную исходя из её предназначения.

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

В статье «Пиши код как Шекспир» обо всём этом рассказано более подробно. Несколько тезисов из неё:

• Выбирайте говорящие названия. Они должны ясно и недвусмысленно показывать, для чего нужна функция. Иначе придётся только догадываться об этом.

• Избегайте неподходящих названий. Очевидно, что в готовом коде не должно быть функций, названия которых не имеют чёткого значения. Или которые названы просто потому что их нужно было как-то назвать.

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

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

Пишите небольшие функции с понятными названиями

Младшие программисты часто создают одну большую функцию, которая выполняет сразу несколько действий. Это становится причиной трёх проблем:
1. Приходится следить одновременно за множеством переменных.
2. Такой функции сложно дать подходящее название.
3. Для такого рода функции сложнее писать юнит-тест.

Эта функция может показаться вам знакомой. С ней самой всё в порядке, но описание всей логики именно таким образом усложняет её чтение, понимание и тестирование.

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

Пусть одна функция выполняет только одну задачу и отвечает только за то, что обозначено в её имени.

Осторожнее с комментариями

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

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

Иногда нам не обойтись без комментирования, потому что нет других вариантов или потому что нет времени воплотить более удачный вариант. Объяснять что-то через сам код сложно, а комментарии к коду помогают пояснить сделанные нами шаги. То есть благодаря комментариям мы можем лучше донести, почему мы написали то, что написали, и почему мы написали это именно таким образом. И в результате другим уже не придётся гадать, что имелось в виду.

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

Итог: читабельный код лучше сложного

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