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

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

Сегодня ведется большая работа по автоматизации этой области; есть инструменты, которые до некоторой степени обеспечивают единообразное форматирование. Intellij-Idea имеет функцию автоматического форматирования для кода Java, которая делает большинство вещей правильно и экономит время. Checkstyle для Java - тоже посланник бога; рано выявляет большинство несоответствий. Я тоже большой поклонник Prettier; Хотя в настоящее время я редко пишу код JavaScript, я использую множество идей, которые я пишу. Хотя в большинстве случаев автоматическое моделирование действительно работает, всегда можно добиться большего. Следующая цитата из Практической типографики здесь очень хорошо применима:

Хорошая типографика оценивается по тому, насколько хорошо она усиливает смысл текста, а не по какой-то абстрактной шкале достоинств. Типографские варианты, которые подходят для одного текста, не обязательно подойдут для другого. (Следствие: хорошие типографы не полагаются на механические решения. Один размер никогда не подходит для всех.)

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

** Весь код взят из случайных репозиториев с открытым исходным кодом

Определения функций:

Рассмотрим следующий фрагмент:

Хотя он читабелен, его можно было бы сделать намного лучше:

Вот что я сделал:

  1. Лексикографическая сортировка по имени класса, чтобы упростить поиск
  2. Первая строка была слишком длинной; длинные строки затрудняют фокусировку кода; это решается очень легко, просто начиная аргументы в следующей строке
  3. Вертикальные линии: убедившись, что все имена аргументов выровнены в одну строку, мы придаем им вид таблицы, которая более удобна для использования, особенно в печатных СМИ. Я выдал два варианта: один с выравниванием имен классов по правому краю и другой с выравниванием по левому краю; Я предпочитаю правильное выравнивание, но чувствую, что оба подхода хорошо служат цели.
  4. Поиск подходящих скобок может быть одной из самых неприятных вещей, с которыми приходится сталкиваться при чтении кода. Простое практическое правило, которое, как я обнаружил, работает для меня, - иметь такой же отступ для закрывающей скобки, что и в строке, содержащей открывающую скобку.

Классы, наследование и интерфейсы:

Сколько раз мы видели фрагмент кода, который выглядит следующим образом:

Форматирование, как показано ниже, делает его более читаемым:

Опять же, обратите внимание на выравнивание в виде таблицы, аналогичное пункту 3 из предыдущего раздела.

Вызов функций:

Я считаю, что здесь нет необходимости изобретать велосипед; Prettier в этом плане неплохо справляется; Очень рекомендую прочитать и статью Вадлера.

Взяв пример прямо из Prettier,

foo(arg1, arg2, arg3); // Concise enough; no need to change
// Can do better
foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());
// Much cleaner!
foo(
  reallyLongArg(),
  omgSoManyParameters(),
  IShouldRefactorThis(),
  isThereSeriouslyAnotherOne()
);

Блоки комментариев

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

  1. Сохранение максимальной ширины строки комментариев 80 символов (или даже меньше). В результате получаются красивые блочные комментарии, которые читатель может легко прочитать. Это очень хорошо согласуется с Практическими правилами типографики Баттерика: Средняя« длина строки должна составлять 45–90 символов (включая пробелы)»
  2. При необходимости используйте теги комментариев; Мне нравится использовать TODO, TECHDEBT https://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags

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

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

Следите за нашей публикацией, чтобы увидеть больше историй о продуктах и ​​дизайне, представленных командой Journal.