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

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

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

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

Программы предназначены для чтения людьми и лишь случайно для выполнения компьютерами. – Дональд Кнут

Именование

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

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

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

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

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

Границы моего языка означают границы моего мира. – Людвиг Витгенштейн

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

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

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

Опыт

Изучите первый фрагмент кода, что делает этот код? В чем “почему”?

Не торопитесь.

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;
        }
    }

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

Общение

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

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