Понимание начинается с выразительных имён

В 2018 году я присоединился к крупному проекту на середине его разработки. Первоначальные инженеры уехали, оставив после себя запутанный и недокументированный код. Работа с таким кодом сложна, потому что вы не можете отличить служебный код от бизнес-логики. Это затрудняет отладку и делает изменения непредсказуемыми, потому что вы не знаете влияние. Это как пытаться отредактировать книгу, не понимая слов.

Многие инженеры считают, что успех измеряется тем, когда код компилируется. Я считаю, что это когда другой инженер (или вы через шесть месяцев) понимает “почему” вашего кода. Первоначальные инженеры затруднили работу будущим инженерам, не документируя и используя непонятные имена. Имена часто являются единственным окном в мыслительный процесс предыдущего инженера.

Дональд Кнут знаменито сказал:

Программы предназначены для чтения людьми и только попутно для выполнения компьютерами. – Donald Knuth

Именование

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

Фил Карлтон, работавший в Netscape, заметил:

В информатике есть только две сложные вещи: инвалидация кэша и именование вещей.
— Phil Karlton

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

Людвиг Витгенштейн, философ первой половины XX века, сказал:

Границы моего языка означают границы моего мира. – Ludwig Wittgenstein

Язык нашего программного обеспечения настолько же описателен, насколько описательны используемые нами имена, и использование неопределённых имён размывает назначение программного обеспечения; использование описательных имён приносит ясность и понимание.

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

Это чувство лучше всего испытать.

Опыт

Посмотрите на первый фрагмент кода, что делает этот код? В чём его смысл?

Не спешите.

public class StringHelper
{
    public string Get(string input1, string input2)
    {
        var result = string.Emtpy;
        if(!string.IsNullOrEmtpy(input1) && !string.IsNullOrEmtpy(input2))
        {
            result = $"{input1} {input2}";
        }
        return result;
    }
}

Приведённый выше код — это простое объединение двух строк. То, что код не говорит вам, — это “почему”. “Почему” так важно, без него сложно изменить поведение, не понимая влияния. Конечно, исследование использования кода, вероятно, выявит его “почему”, но в этом суть. Вам не нужно открывать назначение кода, вместо этого автор должен был оставить подсказки — это их ответственность.

Давайте пересмотрим код, но с небольшим “почему” в нём.

Снова не спешите, обратите внимание на разницу, которую вы чувствуете при чтении этого кода.

    public class FirstAndLastNameFormatter
    {
        public string Concatenate(string firstName, string lastName)
        {
            var fullName = string.Emtpy;
            if(!string.IsNullOrEmtpy(firstName) && !string.IsNullOrEmtpy(lastName))
            {
                fullName = $"{firstName} {lastName}";
            }
            return fullName;
        }
    }

“Почему” оживляет код, есть история для чтения.

Общение

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

Сделайте одолжение следующему инженеру и будьте выразительны в своём коде. Используйте описательные имена и фиксируйте “почему”, потому что кто знает, следующим инженером можете быть вы.