Чистый код обработка ошибок

Роберт Мартин. «Чистый код. Создание, анализ, рефакторинг»

Предисловие

Мелочи важны. 80% работы программиста — поддержка существующего кода. Применение японского принципа 5S к программированию:

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

Введение

Метрика хорошего кода — количество «чертей» в минуту
Профессионализм = знания + опыт. Писать чистый код — тяжело. 3 части книги: теория, практика, эвристические правила.

Глава 1. Чистый код

Код будет всегда (может быть в другом виде, но будет). Хороший код важен. Плохой код мешает работе, но все равно его пишут — потому что пускай работает хоть как-то, чем совсем никак. Работы по рефакторингу откладываются «на потом» (значит, никогда). По мере накопления хаоса в коде производительность стремиться к нулю. Потом случается глобальная переработка (перехуячить все), куда бросают лучшие силы. Возникает гонка между группой поддержки существующего продукта и группой разработки нового (привет, БМП). На чистку кода надо выделять время, даже вопреки требованиям руководства/бизнеса (аналогия: пациент недоволен тем, как врач долго моет руки). Не устранять опасность грязного кода — непрофессионализм. Единственная возможность соблюдать график и не терять производительность — улучшать код. Отличать плохой код от хорошего != уметь писать хорошо. Чувство кода — умение видеть проблемные места и предлагать пути улучшения. Может быть врожденным или приобретенным.
Чистый код в определениях топ-программистов:

• Бьерн Страуструп: элегантность, прямолинейность, эффективность. Чистый код хорошо решает одну задачу.
• Грэди Буч (книга Object oriented analysis and design with applications): простота, четкие абстракции, удобочитаемость, идеи программиста легко и логично считываются
• Дэйв Томас: понятность, поддерживаемость, тесты, минимум зависимостей и простой краткий API, компактность и грамотность
• Майкл Физерс (книга Working effectively with legacy code): чистый код выглядит тщательно написанным, нет очевидных способов улучшения, небезразличность
• Рон Джеффрис: тесты, без нарушения DRY, выразительность, минимум сущностей
• Уорд Каннингем (вдохновитель Design Patterns): делает примерно то, что ожидает читатель кода. Не запутан, логичен, чтение не доставляет трудностей, прост, красив.
  Правило бойскаута: оставь место стоянки чище, чем оно было до твоего прихода. Не сразу глобально, а постепенно, постоянно.

Глава 2. Содержательные имена

Выбор хорошего имени требует усилий и времени, но окупается впоследствии.
Несколько правил хорошего именования сущностей.

Имена должны передавать намерения программиста

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

Избегайте дезинфрмации

Нельзя использовать имена, вызывающие ложные ассоциации. Не использовать в именовании устоявшиеся термины не к месту (например, accountList, если речь действительно не идет о списке – конкретной структуре данных). Остерегаться малозаметных различий в именах – это тоже дезинформация + мешает автокомплиту IDE. Остерегаться похожих символов (1 — l, 0 — O).

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

Классический пример ошибки: product1 и product2. Чуть сложнее: Product, ProductInfo, ProductData – добавление слов не дает никакой полезной информаци.

Сложное правило. Плохие примеры ясны, а как делать хорошо?

Используте удобопроизносимые имена

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

В другой книжке есть яркий пример, который живет и процветает – аббревиатура SQL. Принятое на Западе произношение: «сиквел»; у нас же я слышал только «эс-кю-эль».

Выбирайте имена, удобные для поиска

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

Избегайте схем кодирования имен

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

В тайпскрипте принято интерфесы называть так: IProduct. Пример уместного кодирования, полагаю.

Венгерская запись

В доисторические времена в названии переменной кодировали как раз мета-инфу, например в Fortran первая буква означала тип. Темные времена прошли, не надо так.

Префиксы членов класса

Та же штука, раньше была практика переменным класса давать префикс m_.

Интерфейсы и реализации

А вот и пример с IProduct. В нормальных ОО-языках давать префикс интерфейсам считается зашкваром. Менее зашкварно дать префикс-постфикс реализации.

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

Избегайте мысленных преобразований

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

Имена классов

Имена классов – существительные и их комбинации, не глагол. Избегать общих слов типа Info, Data, Manager, Processor.

Имена методов

Глаголы, глагольные словосочетания. По стандарту javabean: для чтения get, для записи set, для предикатов (логических утверждений) – is.

Избегайте остроумия

Локальные мемы вжопу. Сюда же – сленг и просторечия.

Где-то около этого пункта: я бы рекомендовал следить за элементарной орфографией и не лениться заглядывать в переводчик. А то знаю я некоторых транслэйтэров, блеать

Выберите одно слово для каждой концепции

Автокомплит поможет подставить имя метода, но не расскажет, чем fetch отличается от get, а controller от manager. Терминология должна быть строгой.

Избегайте каламбуров

Не использовать одно и то же слово в двух разных смыслах.

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

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

Используйте имена из пространства задачи

Термины предметной области приложения – тоже ок.

Добавьте содержательный контекст

При взгляде на переменную должно быть понятно, в каком смысловом контексте она используется. Например, мы коды статусов оъединяли и экспортировали единым объектом HTTP. Так же норм добавлять контекстные префиксы: customerName, customerPhone.

Не добавлять избыточный контекст

Будет мешать автокомплиту + в принципе засоряет код, лишние префиксы все равно взглядом будут игнорироваться.

Напоследок

Для выбора хороших имен нужен описательный навык и единый культурный фон в команде. Этому можно научиться и выработать. Не бояться переименовывать неудачные места. Хорошие имена помогут именно читать код + чисто технически добавит удобства в разработке (опять же про автокомплит, хотя бы).

Глава 3. Функции

Функции – первый уровень структуризации программы.

Компактность

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

Блоки и отступы

В блок if, else, while следует помещать одну строку – вызов другой функции. Это сделает исходную функцию компактнее и послужит документированием кода. Нужно избегать вложенность: упростит чтение кода и опять же сделает функцию более компактной.

Правило одной операции

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

Вторую часть (про определение одной операции) понимаю чуть смутно. Нужно найти пример и вернуться к этому разделу.

Один уровень абстрации на функцию

Ещё раз – все команды функции (может быть несколько этапов, это не противоречит правилу одной операции) лежат в одном уровне абстрации. Например: getHtml – высокий, getName – средний, appendSymbol – низкий.

Примеры операций на разных уровнях абстракции немного изменены. Найти яркий пример из своей работы и добавить.

Чтение кода сверху вниз: правило понижения

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

ТО-абзац – дефиниция. Например: renderPageWithSettings – функция, генерирующая код страницы в соответствии с переданными параметрами.

Команды switch

Написать компактный switch или цепочку if/else очень сложно, потому чтоswitch рулит несколькими командами, как правило. Но можно сокрыть эти команды в низкоуровневом классе и не дублировать в коде. Здесь поможет полиморфизм. Переносим switch в абстрактную фабрику, в которой вызовы нужных команд проходят полиморфную передачу через интерфейс.

Здесь тоже не до конца понятен пример и как делать в js. Надо вернуться и разобраться.

Используйте содержательные имена

Имя должны давать понять, что происходит в функции. Не бояться использовать длинные имена, не бояться тратить на это время. Попробовать несколько вариантов. Иногда поиск понятного имени приводит к реструктуризации кода. Ещё нужно быть последовательным в именовании, использовать одинаковую фразеологию. «Функция должна делать примерно то, что вы ожидаете».

Аргументы функций

Идеал – функция без аргументов(нуль-арная). Допустимы унарные и бинарные функции. Тернарных и пониарных функций нужно избегать. При чтении кода аргументы приходится каждый раз интерпретировать. Часто аргумент и имя функции находятся на разных уровнях абстракции. Большое количество аргументов усложняет тестирование, ведь надо покрыть все кейсы, во всех сочетаниях. Фунции с выходными аргументами – вообще зло.

_Выходные – аргументы, чьи значения изменились после выполнения функции. _

Стандартные унарные формы

Два распространенных случая использования унарной функции: проверить некторое условия, связанное с аргументом, и обработка аргумента с последующим вызвращением. Нужно выбирать имена, четко отражающих эти разлиция. Ещё один частый вариант – событие. Функция принимает аргумент, и производит некоторые изменения состояния системы. Опять же – имя должно давать понять, что перед нами именно событие. Следует избегать иных форм унарных функций (речь опять же про выходные аргументы).

Аргументы-флаги

Вызов фунции типа render(true) – это ж пиздец. Сбивает с толку, нужно лезть смотреть сигнатуру + в функции явно будет выполнения нескольких операций.

Бинарные функции

Бинарные функции сложнее в понимании. Совсем лютый ужас – когда в вызове таких функций первый параметр должен игнорироваться. В двух аргументах функции нужен логичный естественный порядок, например: getCoords(latitude, longitude). Если связь условна, то легко перепутать. Бинарные функции – не зло, но следует попробовать преобразовать их в унарные. Например, поиграться с ООП.

В конце главы описаны варианты игр с ООП, которые я не очень хорошо понял. Вернуться, написать свои примеры.

Тернарные функции

Разобраться с тремя аргументами ещё сложнее.

Объекты как аргументы

Если есть 2-3-n аргументов – может их упаковать в отдельный класс? Это может показаться жульничеством, но если переменные передаются совместно, и жить друг без друга не могут, значит это отдельная концепция, заслуживающая своего имени.

Списки аргументов

Если в функцию передается переменное количество аргументов, то есть смысл заключить их в List

Глаголы и ключевые слова

Хорошее имя функции способно рассказать о порядке/обязательности аргумента. Для этого могут служить глаголы и ключевые слова. Например: writeField(name), assertExpectedEqualsActual(expected, actual).

Избавьтесь от побочных эффектов

Побочные эффекты – зло. Функция обещает делать что-то одно, но скрыто совершает что-нибудь дополнительно. Побочные эффекты часто должны быть исполнены в определенный момент времени. За временными привязками следить сложно, особенно когда они скрыты в сайдэффекте. Ну и опять же – правило одной операции нарушается.

Выходные аргументы

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

Разделение команд и запросов

Частный случай принципа одной операции. Функция может изменять состояние объекта или возвращать информацию о нем, но не одновременно. Получится ад. Например, сделать set(name), и если успех – вернуть true. Потом начинается использование типа if (set('unclebob') {...} – жесть.

Используйте исключения вместо возвращения кодов ошибок

Вовзвращать коды ошибок и обрабытывать их – частный случай разделения команд и запросов. Вместо этого лучше воспользоваться try/catch.

Изолируйте блоки try/catch

try/catch смешивает обработку ошибок с нормальным выполнением функции, поэтому из следует выносить в отдельную функцию. Обработка ошибок должна быть одной операцией, и после catch/finally не должно быть ничего другого.

Хороший прием. Посмотреть пример в книге, и написать свой – очень должен пригодится.

Магнит зависимостей Error.java

Обычно создают класс/перечисление всех кодов ошибок, и потом используют во всех остальных классах. Тут есть нюанс (который я не очень уловил, поскольку не знаю Java. Вернуться и проанализировать.)

Не повторяйтесь (DRY)

Дублирование кода увеличивает его объем, делает сложным поддержку/рефакторинг, увеличивет вероятность ошибки. Не надо так.

Структурное программирование

Спорное правило. Оно говорит о том, что функция должна иметь одну точку входа и одну точку выхода. Следствие: в функции должен быть единственный return, в циклах/свичах нельзя использовать break/continue, команды goto – под запретом. Дядя Боб не против, если ты не будешь следовать этому правилу, при условии что функции будут компактными.

Как научиться писать такие функции?

Программирование – тоже сочинительство. Сначала излагаешь мысли, потом «причёсываешь». Пытаться сразу писать чисто не надо.

Завершение

Искусство программирования – это искусство языкового проектирования (где функции – глаголы, а класы – существительные). Средства языка нужно применять для создания более высокоуровневого предметно-ориентированного языка, описывающего вашу систему. Иерархия функций очень поможет. Конечная цель – написать легко читаемый рассказ, «историю системы».

Глава 4. Комментарии

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

Комментарии не компенсируют плохого кода

Не нужно писать пояснения к запутанно написаному модулю: лучше отрефакторить и сделать проще. Не тратьте время на комментирование, тратьте на исправление.

Объясните свои намерения в коде

Следить за наименованием функций и переменных – они могут избавить от комментирования.

Хорошие комментарии

Юридические комментарии

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

Информативные комментарии

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

Представление намерений

Раскрывает намерения вашего архитектурного или логического решения. Отвечает на вопрос: «А почему тут так?»

Прояснения

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

Предупреждения о последствиях

Информирование о нежелательных последствиях выполнения того или иного кода.

Комментарии TODO

// TODO как план на будущее: сделать необходимо, но не получится прямо сейчас.

Усиление

То же самое, что и представление намерений, но там где это незаметно и можно проебать.

Комментарии Javadoc в общедоступных API

Пишешь апишку – напиши комментарии к ней.

Плохия комментарии

О, их будет гораздо больше.

Бормотание

Хочешь написать комментарий – пиши понятно. Не допускайте таких комментариев, для понимания которых придется залезть в другие фукнции/модули.

Избыточные комментарии

Комментарии капитана Очевидность. Дублирует название функции.

Недостоверные комментарии

Ложь в комментарии – устаревшая информация или просто невнимательность.

Обязательные комментарии

Бессмысленная херня, когда зачем-то комментируют каждую функцию.

Журнальные комментарии

Когда-то программисты дописывали в начале модуля журнал всех изменений. Сейчас есть гит и не надо так.

Шум

Это комменты КО и прочий мусор. Это эе тоже придется поддерживать, иначе будет опасненько.

Не используйте комментарии там, где можно использовать фукцию или переменную

В этом заголовке – содержание всей главы

Позиционные маркеры

// Actions ////////////
Форматирование кода с помощью комментариев-заголовков – только там, где это приносит ощутимую пользу.

Комментарии за закрывающей фигурной скобкой

Типа, чтобы не потеряться в многострочной функции/цикле/т.п.:
while { .... } // while
Лучше переписать функцию покороче.

Ссылки на авторов

Опять же: наследие эпохи до VCS.

Закомментированный код

Если код не нужен – удоли.

Комментарии HTML

Когда в тексте комментария встречается разметка – это трудно читать.

Нелокальная информация

Комментарий должен описывать тот кусок кода, рядом с которым написан.

Слишком много информации

Иногда в комменты запихивают чуть ли не статьи с Википедии. Не надо так.

Неочевидные комментарии

Если комментарий нуждается в объяснении – он плохой.

Заголовки функций

Нужно нормально выбирать имена.

Заголовки Javadoc во внутреннем коде

Не приносит пользы, если это не общедоступный код.

Глава 5. Форматирование

Уважение к деталям – хорошо. Зафиксируйте в своей группе правила оформления кода и седуйте им.

Цели форматирования

Стиль кодирования и удобочитаемость имеют большое влияние на сопровождаемость и расширяемость кода

Вертикальное форматирование

Приводится небольшое исследование размера исходных файлов программ на Java (Junit – меньше, Tamcat – больше)

Газетная метафора

Структура файла должна напоминать газетную статью: заглавие, краткое содержание в первом абзаце, а дальше уже факты, подробности. Чем дальше к концу – тем подробнее и ниже уровень абстрации.

Вертикальное разделение концепций

Строка = выражение, условие. Группа строк = законченная мысль. Мысли следует разделять пустыми строками.

Вертикальное сжатие

Вертикальное разрежение разделяет концепции, сжатие – наоборот, подчеркивает тесную связь.

Вертикальные расстояния

По коду трудно навигироваться, приходится постоянно прыгать между кусками кода и файлами. Связанные друг с другом концепции должны распологаться по соседству.
Переменные объявлять как можно ближе к месту использования.
Переменные экземпляров – в начале класса, так как используются многими методами класса (в С++ поступают наоборот, размещая переменные внизу. Так или иначе, надо их держать вместе и не прятать где-то в середине).
Вызывающая функция должна находится над вызываемой.
Концептуально родственные участки должны распологаться поблизости (например, группа функций, выполняющих аналогичные операции).

Вертикальное упорядочение

Еще раз: от высоких абстракций к низким, от вызывающих функций к вызываемым.

Горизонтальное форматирование

Исследование длин строк в файлах. Оптимально – до 120 символов.

Горизонтальное разделение и сжатие

Группировки связанных элементов и разделения разнородных.
Знаки присваивания окружаются пробелами, аргументы не отделяются от имени функции, сами аргументы разделяются пробелами.
В формулах: множители не разделяются пробелами (высокий приоритет операции), слагаемые – разделяются (низкий приоритет). Такой фичи чаще всего нет в инструментах автоматического форматирования, а жаль.

Горизонтальное выравнивание

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

Отступы

Отступы создают иерархию: классы > методы > блоки внутри методов. Не стот нарушать систему отступов для коротких блоков, вытягивая их в одну строку.

Вырожденные области видимости

Иногда тело цикла не содержит команд – является вырожденным. Их стоит избегать, но если не получается – правильно отбивать отступами и скобками.

Правила форматирования в группах

Код продукта должен быть оформлен в одном стиле. Потратьте 10 минут и зафиксируйте правила оформления в вашей команде.

Software Craftmanship Guide() {

Extracts from book Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin. My intention is not to provide a summary, but to share the notes that I want to keep in mind.

Table of Contents

1. Introduction
2. Clean Code
3. Meaningful Names
4. Methods
5. Comments
6. Formatting
7. Objects and Data Structures

Introduction

• 80% or more of what we do is maintenance
• Code is never perfect
• The only valid measurement of code quality: WTFs / minute
• Learning to write clean code is hard work. It requires more than just the knowledge of principles and patterns. You must sweat over it. You must practice it yourself, and watch yourself fail. You must watch others practice it and fail. You must see them stumble and retrace their steps. You must see them agonize over decisions and see the price they pay for making those decisions the wrong way.

[⬆]

Clean Code

• LeBlanc’s law: Later equals never
• Most managers want the truth, even when they don’t act like it. Most managers want good code, even when they are obsessing about the schedule. They may defend the schedule and requirements with passion; but that’s their job. It’s your job to defend the code with equal passion. It is unprofessional for programmers to bend to the will of managers who don’t understand the risks of making messes.
• All developers feel the pressure to make messes in order to meet deadlines. True professionals know that the second part of the conundrum is wrong. You will not make the deadline by making the mess. Indeed, the mess will slow you down instantly, and will force you to miss the deadline. The only way to make the deadline is to keep the code as clean as possible at all times.
• Bad code tempts the mess to grow. When others change bad code, they tend to make it worse. Metaphor: A building with broken windows looks like nobody cares about it. So other people stop caring. They allow more windows to become broken. Eventually they actively break them.
• Clean code should be: Pleasing to read, does one thing well, minimal, looks like it was written by someone who cares
• If we all checked in our code a little cleaner than when we checked it out, the code simply could not rot. The cleanup doesn’t have to be something big. Change one variable name for the better, break up one function that’s a little too large, eliminate one small bit of duplication.

[⬆]

Meaningful Names

• Use intention revealing names. If a name requires a comment, then the name does not reveal its intent.

    // bad
    int d; // elapsed time in days

    // good
    int elapsedTimeInDays;

    // bad
    public List<int[]> getThem() {
		List<int[]> list1 = new ArrayList<int[]>(); 
			for (int[] x : theList)
				if (x[0] == 4) list1.add(x);
		return list1; 
	}

    // good
    public List<int[]> getFlaggedCells() {
		List<int[]> flaggedCells = new ArrayList<int[]>(); 
			for (int[] cell : gameBoard)
				if (cell[STATUS_VALUE] == FLAGGED) 
					flaggedCells.add(cell);
		return flaggedCells; 
	}

• Make meaningful distinctions

  • Imagine you have Product class. If you have another called ProductInfo or ProductData, you have made the names different without making them mean anything different. In the absence of specific conventions, the variable moneyAmount is indistinguishable from money, customerInfo is indistinguishable from customer, accountData is indistinguishable from account, and theMessage is indistinguishable from message.

• Methods should have verb or verb phrase names like postPayment, deletePage, or save. When constructors are overloaded, use static factory methods with names that describe the arguments. Consider enforcing their use by making the corresponding constructors private.

	// bad
	Complex fulcrumPoint = new Complex(23.0);

	// good
	Complex fulcrumPoint = Complex.FromRealNumber(23.0);

• Pick one word per concept. It’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.

• People are afraid of renaming things for fear that some other developers will object. Do not share that fear and be grateful when names change (for the better).

[⬆]

Methods

• The first rule of methods is that they should be small. The second rule of functions is that they should be smaller than that.

• Methods should not be 100 lines long. Methods should hardly ever be 20 lines long.

• Methods should do only one thing. They should do it well. They should do it only.

• How to determine if a method is doing only one thing? Describe the method by describing it as a brief TO paragraph: TO RenderPageWithSetupsAndTeardowns, we check to see whether the page is a test page and if so, we include the setups and teardowns. In either case we render the page in HTML.

• Don’t be afraid to make a name long. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment. The smaller and more focused a method is, the easier it is to choose a descriptive name. Don’t be afraid to spend time choosing a name.

• The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

	// bad
	Circle makeCircle(double x, double y, double radius); 

	// good
	Circle makeCircle(Point center, double radius);

• Passing a boolean into a function is a truly terrible practice. It immediately complicates the signature of the method, loudly proclaiming that this function does more than one thing. It does one thing if the flag is true and another if the flag is false! The method call render(true) is just plain confusing to a poor reader. Mousing over the call and seeing render(boolean isSuite) helps a little, but not that much. We should have split the function into two: renderForSuite() and renderForSingleTest().

• Choosing good names for a function can go a long way toward explaining the intent of the function and the order and intent of the arguments.

	// ok
	void assertEquals(expected, actual)

	// better
	void assertExpectedEqualsActual(expected, actual)

• Anything that forces you to check the function signature is equivalent to a double-take. In the days before object oriented programming it was sometimes necessary to have output arguments. However, much of the need for output arguments disappears in OO languages because this is intended to act as an output argument.

	// Does this function append s as the footer to something? Or does it append some footer to s?
	void appendFooter(s);

	// good
	report.appendFooter();

• Functions should either do something or answer something, but not both.

	// bad
	public boolean set(String attribute, String value);
	
	// “If the username attribute was previously set to unclebob” or 
		// “set the username attribute to unclebob and if that worked then...”
	if (set("username", "unclebob"))...

	// good
	if (attributeExists("username")) {
		setAttribute("username", "unclebob");
		...
	}

• Prefer exceptions to returning error codes

	// Bad
	if (deletePage(page) == E_OK) {
		if (registry.deleteReference(page.name) == E_OK) {
			if (configKeys.deleteKey(page.name.makeKey()) == E_OK){
			logger.log("page deleted");
			} else {
			logger.log("configKey not deleted");
			}
		} else {
			logger.log("deleteReference from registry failed");
		}
	} else {
		logger.log("delete failed");
		return E_ERROR;
	}
	
	// Good
	try {
		deletePage(page);
		registry.deleteReference(page.name);
		configKeys.deleteKey(page.name.makeKey());
	}
	catch (Exception e) {
		logger.log(e.getMessage());
	}

• Functions should do one thing. Error handing is one thing. Thus, a function that handles
  errors should do nothing else. This implies (as in the example above) that if the keyword
  try exists in a function, it should be the very first word in the function and that there
  should be nothing after the catch/finally blocks.

• Duplication may be the root of all evil in software.

• «When I write functions, they come out long and complicated. They have lots of
  indenting and nested loops. They have long argument lists. The names are arbitrary, and
  there is duplicated code. But I also have a suite of unit tests that cover every one of those
  clumsy lines of code. So then I massage and refine that code, splitting out functions,
  changing names, eliminating duplication. I shrink the methods and reorder them. Sometimes I break out whole
  classes, all the while keeping the tests passing. In the end, I wind up with functions that
  follow the rules I’ve laid down in this chapter. I don’t write them that way to start.
  I don’t think anyone could.»

• Functions are the verbs of that language, and classes are the nouns. Master programmers think
  of systems as stories to be told rather than programs to be written.

[⬆]

Comments

• «Don’t comment bad code — rewrite it.»

• The proper use of comments is to compensate for our failure to express ourself in
  code. Comments are always failures. We must have them because we cannot always figure out how to express
  ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where
  you need to write a comment, think it through and see whether there isn’t some way to turn
  the tables and express yourself in code.

• The older a comment is, and the farther away it is from the code it describes,
  the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically
  maintain them.

• Comments Do Not Make Up for Bad Code! One of the more common motivations for writing comments is bad code.
  We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves,
  “Ooh, I’d better comment that!” No! You’d better clean it! Clear and expressive code with few comments is
  far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the
  comments that explain the mess you’ve made, spend it cleaning that mess.

• Explain yourself in code

	// Bad:
	
	// Check to see if the employee is eligible for full benefits
		if ((employee.flags & HOURLY_FLAG) &&
		(employee.age > 65))
	
	// Good:
	if (employee.isEligibleForFullBenefits())

• Avoid redundant comments: These comments below probably takes longer to read than the code itself

	// Utility method that returns when this.closed is true. Throws an exception
	// if the timeout is reached.
	public synchronized void waitForClose(final long timeoutMillis)	throws Exception {
		if(!closed) {
			wait(timeoutMillis);
		if(!closed)
			throw new Exception("MockResponseSender could not be closed");
		}
	}

• Avoid mandated comments: It is just plain silly to have a rule that says that every function must have a javadoc, or
  every variable must have a comment.

	/**
	*
	* @param title The title of the CD
	* @param author The author of the CD
	* @param tracks The number of tracks on the CD
	* @param durationInMinutes The duration of the CD in minutes
	*/
	public void addCD(String title, String author, int tracks, int durationInMinutes) {
		CD cd = new CD();
		cd.title = title;
		cd.author = author;
		cd.tracks = tracks;
		cd.duration = duration;
		cdList.add(cd);
	}

• Don’t use a comment when you can use a function or variable

	// Bad:
	
	// does the module from the global list <mod> depend on the subsystem we are part of?
	if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
	
	// Good:
	ArrayList moduleDependees = smodule.getDependSubsystems();
	String ourSubSystem = subSysMod.getSubSystem();
	if (moduleDependees.contains(ourSubSystem))

• Few practices are as odious as commenting-out code. Don’t do this! Others who see that commented-out code won’t
  have the courage to delete it. They’ll think it is there for a reason and is too important to delete.
  So commented-out code gathers like dregs at the bottom of a bad bottle of wine. There was a time, back in the sixties,
  when commenting-out code might have been useful. But we’ve had good source code control systems for a very long time now.
  Those systems will remember the code for us.

[⬆]

Formatting

• Dependent Functions: If one function calls another, they should be vertically close,
  and the caller should be above the callee, if at all possible. This gives the program a natural flow.

[⬆]

Objects

to be written

[⬆]

Error Handling

• Many code bases are com- pletely dominated by error handling. When I say dominated, I don’t mean that error han- dling is all that they do. I mean that it is nearly impossible to see what the code does because of all of the scattered error handling. Error handling is important, but if it obscures logic, it’s wrong.

• Don’t return null. I can’t begin to count the number of applications I’ve seen in which nearly every other line was a check for null.

public void registerItem(Item item) { if (item != null) {
	ItemRegistry registry = peristentStore.getItemRegistry(); 
	if (registry != null) {
		Item existing = registry.getItem(item.getID());
		if (existing.getBillingPeriod().hasRetailOwner()) {
			existing.register(item); }
		} 
	}
}

If you are tempted to return null from a method, consider throwing an exception or returning a SPECIAL CASE object instead. If you are calling a null-returning method from a third-party API, consider wrapping that method with a method that either throws an exception or returns a special case object.

Bad:

List<Employee> employees = getEmployees(); 
if (employees != null) {
	for(Employee e : employees) { 
		totalPay += e.getPay();
	} 
}

Right now, getEmployees can return null, but does it have to? If we change getEmployee so that it returns an empty list, we can clean up the code:

List<Employee> employees = getEmployees(); 
for(Employee e : employees) {
	totalPay += e.getPay(); 
}

};

Software Craftmanship Guide() {

Extracts from book Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin. My intention is not to provide a summary, but to share the notes that I want to keep in mind.

Table of Contents

1. Introduction
2. Clean Code
3. Meaningful Names
4. Methods
5. Comments
6. Formatting
7. Objects and Data Structures

Introduction

• 80% or more of what we do is maintenance
• Code is never perfect
• The only valid measurement of code quality: WTFs / minute
• Learning to write clean code is hard work. It requires more than just the knowledge of principles and patterns. You must sweat over it. You must practice it yourself, and watch yourself fail. You must watch others practice it and fail. You must see them stumble and retrace their steps. You must see them agonize over decisions and see the price they pay for making those decisions the wrong way.

[⬆]

Clean Code

• LeBlanc’s law: Later equals never
• Most managers want the truth, even when they don’t act like it. Most managers want good code, even when they are obsessing about the schedule. They may defend the schedule and requirements with passion; but that’s their job. It’s your job to defend the code with equal passion. It is unprofessional for programmers to bend to the will of managers who don’t understand the risks of making messes.
• All developers feel the pressure to make messes in order to meet deadlines. True professionals know that the second part of the conundrum is wrong. You will not make the deadline by making the mess. Indeed, the mess will slow you down instantly, and will force you to miss the deadline. The only way to make the deadline is to keep the code as clean as possible at all times.
• Bad code tempts the mess to grow. When others change bad code, they tend to make it worse. Metaphor: A building with broken windows looks like nobody cares about it. So other people stop caring. They allow more windows to become broken. Eventually they actively break them.
• Clean code should be: Pleasing to read, does one thing well, minimal, looks like it was written by someone who cares
• If we all checked in our code a little cleaner than when we checked it out, the code simply could not rot. The cleanup doesn’t have to be something big. Change one variable name for the better, break up one function that’s a little too large, eliminate one small bit of duplication.

[⬆]

Meaningful Names

• Use intention revealing names. If a name requires a comment, then the name does not reveal its intent.

    // bad
    int d; // elapsed time in days

    // good
    int elapsedTimeInDays;

    // bad
    public List<int[]> getThem() {
		List<int[]> list1 = new ArrayList<int[]>(); 
			for (int[] x : theList)
				if (x[0] == 4) list1.add(x);
		return list1; 
	}

    // good
    public List<int[]> getFlaggedCells() {
		List<int[]> flaggedCells = new ArrayList<int[]>(); 
			for (int[] cell : gameBoard)
				if (cell[STATUS_VALUE] == FLAGGED) 
					flaggedCells.add(cell);
		return flaggedCells; 
	}

• Make meaningful distinctions

  • Imagine you have Product class. If you have another called ProductInfo or ProductData, you have made the names different without making them mean anything different. In the absence of specific conventions, the variable moneyAmount is indistinguishable from money, customerInfo is indistinguishable from customer, accountData is indistinguishable from account, and theMessage is indistinguishable from message.

• Methods should have verb or verb phrase names like postPayment, deletePage, or save. When constructors are overloaded, use static factory methods with names that describe the arguments. Consider enforcing their use by making the corresponding constructors private.

	// bad
	Complex fulcrumPoint = new Complex(23.0);

	// good
	Complex fulcrumPoint = Complex.FromRealNumber(23.0);

• Pick one word per concept. It’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.

• People are afraid of renaming things for fear that some other developers will object. Do not share that fear and be grateful when names change (for the better).

[⬆]

Methods

• The first rule of methods is that they should be small. The second rule of functions is that they should be smaller than that.

• Methods should not be 100 lines long. Methods should hardly ever be 20 lines long.

• Methods should do only one thing. They should do it well. They should do it only.

• How to determine if a method is doing only one thing? Describe the method by describing it as a brief TO paragraph: TO RenderPageWithSetupsAndTeardowns, we check to see whether the page is a test page and if so, we include the setups and teardowns. In either case we render the page in HTML.

• Don’t be afraid to make a name long. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment. The smaller and more focused a method is, the easier it is to choose a descriptive name. Don’t be afraid to spend time choosing a name.

• The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

	// bad
	Circle makeCircle(double x, double y, double radius); 

	// good
	Circle makeCircle(Point center, double radius);

• Passing a boolean into a function is a truly terrible practice. It immediately complicates the signature of the method, loudly proclaiming that this function does more than one thing. It does one thing if the flag is true and another if the flag is false! The method call render(true) is just plain confusing to a poor reader. Mousing over the call and seeing render(boolean isSuite) helps a little, but not that much. We should have split the function into two: renderForSuite() and renderForSingleTest().

• Choosing good names for a function can go a long way toward explaining the intent of the function and the order and intent of the arguments.

	// ok
	void assertEquals(expected, actual)

	// better
	void assertExpectedEqualsActual(expected, actual)

• Anything that forces you to check the function signature is equivalent to a double-take. In the days before object oriented programming it was sometimes necessary to have output arguments. However, much of the need for output arguments disappears in OO languages because this is intended to act as an output argument.

	// Does this function append s as the footer to something? Or does it append some footer to s?
	void appendFooter(s);

	// good
	report.appendFooter();

• Functions should either do something or answer something, but not both.

	// bad
	public boolean set(String attribute, String value);
	
	// “If the username attribute was previously set to unclebob” or 
		// “set the username attribute to unclebob and if that worked then...”
	if (set("username", "unclebob"))...

	// good
	if (attributeExists("username")) {
		setAttribute("username", "unclebob");
		...
	}

• Prefer exceptions to returning error codes

	// Bad
	if (deletePage(page) == E_OK) {
		if (registry.deleteReference(page.name) == E_OK) {
			if (configKeys.deleteKey(page.name.makeKey()) == E_OK){
			logger.log("page deleted");
			} else {
			logger.log("configKey not deleted");
			}
		} else {
			logger.log("deleteReference from registry failed");
		}
	} else {
		logger.log("delete failed");
		return E_ERROR;
	}
	
	// Good
	try {
		deletePage(page);
		registry.deleteReference(page.name);
		configKeys.deleteKey(page.name.makeKey());
	}
	catch (Exception e) {
		logger.log(e.getMessage());
	}

• Functions should do one thing. Error handing is one thing. Thus, a function that handles
  errors should do nothing else. This implies (as in the example above) that if the keyword
  try exists in a function, it should be the very first word in the function and that there
  should be nothing after the catch/finally blocks.

• Duplication may be the root of all evil in software.

• «When I write functions, they come out long and complicated. They have lots of
  indenting and nested loops. They have long argument lists. The names are arbitrary, and
  there is duplicated code. But I also have a suite of unit tests that cover every one of those
  clumsy lines of code. So then I massage and refine that code, splitting out functions,
  changing names, eliminating duplication. I shrink the methods and reorder them. Sometimes I break out whole
  classes, all the while keeping the tests passing. In the end, I wind up with functions that
  follow the rules I’ve laid down in this chapter. I don’t write them that way to start.
  I don’t think anyone could.»

• Functions are the verbs of that language, and classes are the nouns. Master programmers think
  of systems as stories to be told rather than programs to be written.

[⬆]

Comments

• «Don’t comment bad code — rewrite it.»

• The proper use of comments is to compensate for our failure to express ourself in
  code. Comments are always failures. We must have them because we cannot always figure out how to express
  ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where
  you need to write a comment, think it through and see whether there isn’t some way to turn
  the tables and express yourself in code.

• The older a comment is, and the farther away it is from the code it describes,
  the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically
  maintain them.

• Comments Do Not Make Up for Bad Code! One of the more common motivations for writing comments is bad code.
  We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves,
  “Ooh, I’d better comment that!” No! You’d better clean it! Clear and expressive code with few comments is
  far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the
  comments that explain the mess you’ve made, spend it cleaning that mess.

• Explain yourself in code

	// Bad:
	
	// Check to see if the employee is eligible for full benefits
		if ((employee.flags & HOURLY_FLAG) &&
		(employee.age > 65))
	
	// Good:
	if (employee.isEligibleForFullBenefits())

• Avoid redundant comments: These comments below probably takes longer to read than the code itself

	// Utility method that returns when this.closed is true. Throws an exception
	// if the timeout is reached.
	public synchronized void waitForClose(final long timeoutMillis)	throws Exception {
		if(!closed) {
			wait(timeoutMillis);
		if(!closed)
			throw new Exception("MockResponseSender could not be closed");
		}
	}

• Avoid mandated comments: It is just plain silly to have a rule that says that every function must have a javadoc, or
  every variable must have a comment.

	/**
	*
	* @param title The title of the CD
	* @param author The author of the CD
	* @param tracks The number of tracks on the CD
	* @param durationInMinutes The duration of the CD in minutes
	*/
	public void addCD(String title, String author, int tracks, int durationInMinutes) {
		CD cd = new CD();
		cd.title = title;
		cd.author = author;
		cd.tracks = tracks;
		cd.duration = duration;
		cdList.add(cd);
	}

• Don’t use a comment when you can use a function or variable

	// Bad:
	
	// does the module from the global list <mod> depend on the subsystem we are part of?
	if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
	
	// Good:
	ArrayList moduleDependees = smodule.getDependSubsystems();
	String ourSubSystem = subSysMod.getSubSystem();
	if (moduleDependees.contains(ourSubSystem))

• Few practices are as odious as commenting-out code. Don’t do this! Others who see that commented-out code won’t
  have the courage to delete it. They’ll think it is there for a reason and is too important to delete.
  So commented-out code gathers like dregs at the bottom of a bad bottle of wine. There was a time, back in the sixties,
  when commenting-out code might have been useful. But we’ve had good source code control systems for a very long time now.
  Those systems will remember the code for us.

[⬆]

Formatting

• Dependent Functions: If one function calls another, they should be vertically close,
  and the caller should be above the callee, if at all possible. This gives the program a natural flow.

[⬆]

Objects

to be written

[⬆]

Error Handling

• Many code bases are com- pletely dominated by error handling. When I say dominated, I don’t mean that error han- dling is all that they do. I mean that it is nearly impossible to see what the code does because of all of the scattered error handling. Error handling is important, but if it obscures logic, it’s wrong.

• Don’t return null. I can’t begin to count the number of applications I’ve seen in which nearly every other line was a check for null.

public void registerItem(Item item) { if (item != null) {
	ItemRegistry registry = peristentStore.getItemRegistry(); 
	if (registry != null) {
		Item existing = registry.getItem(item.getID());
		if (existing.getBillingPeriod().hasRetailOwner()) {
			existing.register(item); }
		} 
	}
}

If you are tempted to return null from a method, consider throwing an exception or returning a SPECIAL CASE object instead. If you are calling a null-returning method from a third-party API, consider wrapping that method with a method that either throws an exception or returns a special case object.

Bad:

List<Employee> employees = getEmployees(); 
if (employees != null) {
	for(Employee e : employees) { 
		totalPay += e.getPay();
	} 
}

Right now, getEmployees can return null, but does it have to? If we change getEmployee so that it returns an empty list, we can clean up the code:

List<Employee> employees = getEmployees(); 
for(Employee e : employees) {
	totalPay += e.getPay(); 
}

};