Pull to refresh

Код, который приятно читать

Reading time 2 min
Views 3.6K

Хороший код


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

Основное правило

Я считаю, что читаемым является код, в который можно не вчитываться.
То есть, пары-тройки строк дожно быть достаточно, чтобы сказать, что делает класс или метод. Ещё пары-тройки — чтобы примерно сказать, как он это делает.

Прочие замечания

Я заметил, что есть ещё несколько довольно общих правил, которые делают код симпатичнее.

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

2. Файлы не длиннее 200-300 строк  У громадных файлов та же проблема, что и у некоторых швейцарских ножей: невозможно запомнить, что эта хрень делает.
Описать, что делает файл (или класс) становится невозможно. Каждый последующий разработчик, понимает, что ничего не понятно, и смело добавляет новый метод. Самое страшное — это CommonUtils (или common_utils.h).

3. Отступы  Без них никуда. К счастью, почти все современные IDE проставляют их автоматически.

4. Названия идентификаторов  Тут тоже всё ясно. Очень много было сказано про осмысленные названия переменных, методов и классов.
Кстати, очень здорово договориться с коллегами про значения слов «retrieve», «fetch», «get», «helper», «utils», «controller».

5. Блоки кода  Каждый метод обычно может быть разбит на несколько логических блоков. Например, проверка входных параметров, посылка сообщения дедушке, проверка ответа.
Очень удобно читать код, когда между этими блоками есть разделитель. Обычно хватает пустой линии. Идеальный вариант — пустая линия и пара слов о том, что будет происходить в следующем блоке.

6. Описание полей  Иногда названия поля не достаточно, чтобы отразить его смысл. Тогда полезен комментарий, поясняющий, что к чему.
Более того, я заметил, что в случае многопоточного приложения удобно указывать, каким мьютексом защищено поле (то есть, каким мьютексом надо завладеть, чтобы поменять это поле).

7. Комментарии публичных методов  Каждый раз, когда я вызываю метод, мне очень интересно, что этот метод делает, что он ожидает от входных параметров, и чем всё может кончиться.
Конечно, это может быть очевидно из названия метода. Однако, иногда нужны дополнительные пояснения. Меня, например, очень часто волнует, будет ли метод совершать IO-операцию, будет ли он интенсивно использовать процессор или есть ли ещё какой-нибудь подвох.

8. Отсутствие закомменченного кода  Думаю, все с этим сталкивались. 5-10 строчек кода закомменчено и стоит приписка: Fix for bug 24132.
Мне кажется, что если код не нужен, то его следует удалить. Для ответа на вопрос «а где же мои любимые 5-10 строчек кода?» существует система контроля версий.

Пример

На мой вкус такой класс весьма читаемый:

Code Sample


А как вам кажется?
Какие ещё правила вы используете? Как сделать код читаемее?
Tags:
Hubs:
+53
Comments 242
Comments Comments 242

Articles