Как написать легко описываемый код

Привет, Хабр!

Часто ли у вас было, что вы или ваши коллеги не могли описать свой собственный код парочкой фраз?

Предлагаю вашему вниманию перевод статьи "How to write easily describable code" автора Cedd Burge, в которой он делится советом, как избежать таких ситуаций.

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

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

Пример неописуемого кода

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

Ниже приведенное общее решение определяет, является ли год високосным.

(divisibleBy(4) and not divisibleBy(100)) or divisibleBy(400)

Это простой код. Он вызывает функции 3 раза, имеет 3 оператора (и, или, нет) и два уровня вложенности.

Но я думаю, что, если вам дадут одну секунду для описания этого алгоритма с помощью слов, у вас появятся трудности.

Может быть, «год является високосным, если он делится на 4 и не делится на 100, или делится на 400»?

Проблема состоит в том, что в словах, в отличии от кода, нет скобок. Поэтому словами сложно адекватно описать условие и то, относится ли «или делится на 400» к «делится на 4» или к «не делится на 400». Для обхода этой проблемы, вы можете указывать скобки рукой или делать более продолжительные паузы между условиями, но вероятность ошибки всё равно останется большой.

Рефакторинг описываемого кода

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

"400 лет — это уникальный случай. Если год делится на 400, то это високосный год. 100 лет — это тоже уникальный случай. Если год делится на 100, то это не високосный год, если только он не делится на 400, таким образом, приоритет у особого случая "400 лет". Если особые случаи отсутствуют, то этот год — високосный, при условии, что он делится на 4».

Звучит понятно, но не лаконично, поэтому мы немного сократим текст:
«Если год делится на 400, то он високосный. Если же он делится на 100, то это обычный год, но при делении на 4, это високосный год".

Если превратим эти слова в код, мы получим что-то следующее:

if divisbleBy(400):
        return LeapYear
    elif divisbleBy(100)
        return NormalYear
    elif divisbleBy(4):
        return LeapYear
    else:
        return NormalYear

Выводы

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

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