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

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

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

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

Предлагаю вашему вниманию перевод статьи «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

Выводы

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

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

Об этой статье

Была ли эта статья полезной?

В этой главе мы напишем первую программу на C++ и научимся печатать и считывать с клавиатуры строки и числа.

Функция main

Пожалуй, самая простая и короткая программа на C++ — это программа, которая ничего не делает. Она выглядит так:

int main() {
    return 0;
}

Здесь определяется функция с именем main, которая не принимает никаких аргументов (внутри круглых скобок ничего нет) и не выполняет никаких содержательных команд. В каждой программе на C++ должна быть ровно одна функция main — с неё начинается выполнение программы.

У функции указан тип возвращаемого значения int (целое число), и она возвращает 0 — в данном случае это сообщение для операционной системы, что программа выполнилась успешно. И наоборот, ненулевой код возврата означает, что при выполнении возникла ошибка (например, программа получила некорректные входные данные).

Для функции main разрешается не писать завершающий return 0, чем мы и будем пользоваться далее для краткости. Поэтому самую короткую программу можно было бы написать вот так:

int main() {
}

Hello, world!

Соблюдая традиции, напишем простейшую программу на C++ — она выведет приветствие в консоль:

#include <iostream>

int main() {
    std::cout << "Hello, world!n";
    return 0;
}

Разберём её подробнее.

Директива #include <iostream> подключает стандартный библиотечный заголовочный файл для работы с потоками ввода-вывода (input-output streams). Для печати мы используем поток вывода std::cout, где cout расшифровывается как character output, то есть «символьный вывод».

В теле функции main мы передаём в std::cout строку Hello, world! с завершающим переводом строки n. В зависимости от операционной системы n будет преобразован в один или в два управляющих байта с кодами 0A или 0D 0A соответственно.

Инструкции внутри тела функции завершаются точками с запятой.

Компиляция из командной строки

Вы можете запустить эту программу из какой-нибудь IDE. Мы же покажем, как собрать её в консоли Linux с помощью компилятора clang++.

Пусть файл с программой называется hello.cpp. Запустим компилятор:

$ clang++ hello.cpp -o hello

В результате мы получим исполняемый файл с именем hello, который теперь можно просто запустить. Он напечатает на экране ожидаемую фразу:

$ ./hello
Hello, world!

Если опцию -o не указать, то сгенерированный исполняемый файл будет по умолчанию назван a.out. В дальнейшем для простых примеров мы будем использовать краткую форму записи команды:

$ clang++ hello.cpp && ./a.out
Hello, world!

С её помощью мы компилируем программу и в случае успеха компиляции сразу же запускаем.

Комментарии

Комментарии — это фрагменты программы, которые игнорируются компилятором и предназначены для программиста. В C++ есть два вида комментариев — однострочные и многострочные:

int main() {  // однострочный комментарий продолжается до конца строки

/* Пример
   многострочного
   комментария */
}

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

Хорошо: комментировать, что делает библиотека, функция или класс или почему этот код написан именно так.

Плохо: комментировать, что происходит на отдельной строчке. Это признак того, что код можно написать лучше.

Библиотеки и заголовочные файлы

Библиотека — это код, который можно переиспользовать в разных программах. В стандарт языка C++ входит спецификация так называемой стандартной библиотеки, которая поставляется вместе с компилятором. Она содержит различные структуры данных (контейнеры), типовые алгоритмы, средства ввода-вывода и т. д. Конструкции из этой библиотеки предваряются префиксом std::, который обозначает пространство имён.

Чтобы воспользоваться теми или иными библиотечными конструкциями, в начале программы надо подключить нужные заголовочные файлы. Так, в программе, которая печатала Hello, world!, нам уже встречался заголовочный файл iostream и конструкция std::cout из стандартной библиотеки.

Для C++ существует также множество сторонних библиотек. Наиболее известной коллекцией сторонних библиотек для C++ является Boost.

Ошибки компиляции

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

Рассмотрим пример такой программы:

#include <iostream>

int main() {
    cout << "Hello, worldn"

Компилятор может выдать такие сообщения:

$ clang++ hello.cpp
hello.cpp:4:5: error: use of undeclared identifier 'cout'; did you mean 'std::cout'?
    cout << "Hello, world!n"
    ^~~~
    std::cout

hello.cpp:4:30: error: expected ';' after expression
    cout << "Hello, world!n"
                             ^
                             ;

hello.cpp:5:1: error: expected '}'
^
a.cpp:3:12: note: to match this '{'
int main() {
           ^
3 errors generated.

Первая ошибка — вместо std::cout мы написали cout. Вторая ошибка — не поставили точку запятой после "Hello, world!n". Наконец, третья – не закрыли фигурную скобку с телом функции.

Ошибки компиляции (compile errors) следует отличать от возможных ошибок времени выполнения (runtime errors), которые происходят после запуска программы и, как правило, зависят от входных данных, неизвестных во время компиляции.

Отступы и оформление кода

Фрагменты программы на C++ могут быть иерархически вложены друг в друга. На верхнем уровне находятся функции, внутри них написаны их тела, в теле могут быть составные операторы, и так далее.

Среди программистов есть соглашение — писать внутренние блоки кода с отступами вправо: компилятор полностью игнорирует эти отступы, а код читать удобнее. Мы будем использовать отступы в четыре пробела. Также мы будем придерживаться стиля оформления кода, принятого в Яндексе. Имена переменных мы будем писать с маленькой буквы, имена функций и классов — с большой (если речь не идёт о конструкциях стандартной библиотеки, где действуют другие соглашения).

Переменные

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

Type name;

где вместо Type — конкретный тип данных (например, строка или число), а вместо name — имя переменной. Имена переменных должны состоять из латинских букв, цифр и знаков подчёркивания и не должны начинаться с цифры. Также можно в одной строке определить несколько переменных одного типа:

Type name1 = value1, name2 = value2, name3 = value3;

Например:

#include <string>  // библиотека, в которой определён тип std::string

int main() {
    // Определяем переменную value целочисленного типа int
    int value;

    // Определяем переменные name и surname типа std::string (текстовая строка)
    std::string name, surname;
}

В этом примере мы используем встроенный в язык тип int (от слова integer — целое число) и поставляемый со стандартной библиотекой тип std::string. (Можно было бы использовать для строк встроенный тип с массивом символов, но это неудобно.)

Тип переменной должен быть известен компилятору во время компиляции.

От типа зависит:

• сколько байтов памяти потребуется для хранения данных;
• как интерпретировать эти байты;
• какие операции с этой переменной возможны.

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

Важно понимать, что тип остаётся с переменной навсегда. Например, присвоить целочисленной переменной строку не получится — это вызовет ошибку компиляции:

int main() {
    int value;
    value = 42;  // OK
    value = "Hello!";  // ошибка компиляции!
}

Переменные можно сразу проинициализировать значением. В С++ есть много разных способов инициализации. Нам пока будет достаточно способа, который называется copy initialization:

#include <string>

int main() {
    int value = 42;
    std::string title = "Bjarne Stroustrup";
}

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

Потоковый ввод и вывод

Поток — это абстракция для чтения и записи последовательности данных в форматированном виде.

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

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

В программе Hello, world! нам уже встречался поток вывода std::cout, по умолчанию связанный с экраном консоли. Познакомимся с потоком ввода std::cin, связанным с клавиатурой. Для его использования нужен тот же заголовочный файл iostream.

Рассмотрим программу, которая спрашивает имя пользователя и печатает персональное приветствие:

#include <iostream>
#include <string>

int main() {
    std::string name;  // объявляем переменную name
    std::cout << "What is your name?n";
    std::cin >> name;  // считываем её значение с клавиатуры
    std::cout << "Hello, " << name << "!n";
}

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

В нашем примере в переменную name считается одно слово, которое будет выведено в ответном сообщении. Пример работы программы:

What is your name?
Alice
Hello, Alice!

Однако если ввести строку из нескольких слов с пробелами, то в name запишется только первое слово:

$ ./a.out
What is your name?
Alice Liddell
Hello, Alice!

Дело в том, что cin читает поток данных до ближайшего пробельного разделителя (пробела, табуляции, перевода строки или просто конца файла). Чтобы считать в строковую переменную всю строчку целиком (не включая завершающий символ перевода строки), нужно использовать функцию std::getline из заголовочного файла string:

#include <iostream>
#include <string>

int main() {
    std::string name;
    std::getline(std::cin, name);
    std::cout << "Hello, " << name << "!n";
}

В этом примере мы печатаем в одном выражении друг за другом несколько строк ("Hello, ", name и "!n"), разделённых угловыми скобками <<. Таким образом, cin и cout позволяют кратко считывать и печатать несколько объектов одной командой.

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

int main() {
    int a;
    int b;
    int c;
    std::cin >> a >> b >> c;
}

Напечатать их значения можно следующим образом:

std::cout << a << " " << b << " " << c << "n";

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

[Эта статья была написана Дэвидом Старром]

Поскольку мы читаем больше кода, чем пишем, имеет смысл писать код, который легко читать. Но то, что делает код более читабельным, похоже на вопрос «Что делает одного автора более читабельным, чем другого?»

Есть некоторые принципы, с которыми разработчики склонны соглашаться — особенно, как выразить свое намерение в коде Попросите программиста назвать некоторые из них, и вы, вероятно, услышите что-то вроде этого:

• Хорошо названные переменные, методы и класс
• Последовательное форматирование
• Маленькие методы
• Минимальная вложенность и кодовые ветви

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

Улучшение вашего кода: боулинг

В игре в боулинг есть простой алгоритм для подсчета очков в игре, но я заметил, что большинство игроков в боулинг не знают, как на самом деле их игра оценивается. Базовая оценка проста: вы получаете одно очко за каждый сбитый штифт. Есть бонусы, если вы сбили все десять пинов. Если котелок наносит удар (все 10 кеглей за один бросок), счет увеличивается на десять, плюс добавляется значение следующих 2 бросков. Если котелок получает запасной (все десять кеглей за 2 броска), то счет увеличивается на десять плюс стоимость следующего броска.

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

Загружаемый zip-файл содержит 2 рабочих примера решений ( до  и после )  ката для боулинга Боба Мартина ; если вы не слышали об этом, это отличное упражнение для изучения. Класс Game является предметом этой статьи. Метод Roll () класса Game принимает количество выбитых кеглей, когда мяч катится по переулку, и предоставляет метод GetScore () для определения итоговой оценки боулера.

Код C # в   папке before загружаемого кода органически вырос за набор небольших, но возрастающих требований. Я не улучшил его ни на каком этапе, поэтому, к сожалению, стиль похож на производственный код, который я вижу все время. Если вы не знакомы с оценкой боулинга, посмотрите, сможете ли вы понять это, прочитав алгоритм в коде. Не беспокойтесь, если он слишком ошеломляет, чтобы не отставать от индексации массива, мы исправим эту реализацию, чтобы сделать алгоритм более очевидным.

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

int[] _rolls = new int[21];

int _rollIndex = 0;

internal void Roll(int i)

{

_rolls[_rollIndex++] = i;

}

Следующее, что может улучшить ситуацию, — это имя переменной, переданной в метод Roll. Чего ожидает этот метод? Очевидно, целое число, но что это целое представляет? Вот что показывает моя IDE, когда я смотрю на этот метод с точки зрения вызывающего.

Не самый интуитивно понятный метод подписи, не так ли? Если я хочу узнать, что представляет собой «i», мне, вероятно, нужно пойти в этот класс и посмотреть на детали, чтобы выяснить намерение. Изображение ниже — то, что я вижу после переименования переменной, чтобы лучше соответствовать цели метода Roll (). Это более интуитивный метод подписи. Я вижу, что параметр представляет количество пинов, сбитых за один бросок.

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

int rollIndex = 0;

int score = 0;

for (int frameIndex = 0; frameIndex < 10; frameIndex++)

{

. . .

}

Это немного лучше. Теперь мы видим, что алгоритм работает, хотя массив _rolls по одному кадру за раз, а переменная rollIndex отслеживает броски в каждом кадре. Мы также можем сразу увидеть, что результат, который мы вычисляем, на самом деле является результатом, хотя это, как правило, подразумевается именем метода GetScore (), это все еще добавляет немного ясности.

Пойдя дальше, я приведу некоторые условные коды к методу (называемому «Рефакторинг метода Exrtact Method»). Например, я изменю if (_rolls [rollIndex] == 10) на if (ThisFrameIsAStrike (rollIndex). Теперь код начинает читать как простой разговорный язык. Эти изменения чуть-чуть замедляют запись, но ускоряют читатель очень много — и мы знаем, что большая часть обслуживания читает, а не пишет.

Но как насчет фактической оценки? Требуется немного концентрации, чтобы пробраться сквозь эти элементы массива и понять, что происходит. Давайте выполним еще немного рефакторинга Extract Method, чтобы немного их очистить. Полученный класс содержит больше кода из-за частных методов разъяснения, но логику основного алгоритма GetScore () теперь легко читать. Проверьте  решение после, чтобы увидеть окончательную реализацию класса Game.cs.

for (int frameIndex = 0; frameIndex < 10; frameIndex++)

{

if (FrameIsStrike(rollIndex))

{

. . .

}

else if (FrameIsSpare(rollIndex))

{

. . .

}

else

{

. . .

}

}

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

Давайте поговорим еще об одном примере, прежде чем называть это днем.

В поисках простых чисел

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

Метод GetPrimes () принимает целое число и возвращает его простые множители. Переменные уже имеют правильные имена, и если вы потратите некоторое время на чтение кода, вы, вероятно, поймете его намерения.

public int[] Factor(int numToFactor)

{

var factors = new List<int>();

var possiblePrime = 2;



while (numToFactor > 1)

{

while (numToFactor%possiblePrime == 0)

{

factors.Add(possiblePrime);

numToFactor /= possiblePrime;

}

possiblePrime++;

}

return factors.ToArray();

}

Хотя это полное и работающее решение для ката Prime Factors, многие практикующие ката используют этот код, чтобы сделать его еще более коротким и кратким. Фактически, основная логика может быть выражена в 2 коротких строках кода.

public int[] Factor(int numToFactor)

{

var factors = new List<int>();



for (int candidate = 2; numToFactor > 1; candidate++)

for (; numToFactor % candidate == 0; numToFactor /= candidate)

factors.Add(candidate);





return factors.ToArray();

}

Хотя в этой реализации код действительно короче, его труднее читать. Эта реализация берет стандартные структуры цикла for и использует их способами, которые мы не привыкли видеть. Внешний цикл сравнивает numToFactor в слоте, который мы обычно ожидаем увидеть сравниваемым индексатором. Внутренний цикл выглядит немного странно, поскольку он даже не объявляет индексатор. Это вполне допустимо в C #, но это не та конструкция, которую часто можно увидеть.

Найдите минутку, чтобы попытаться найти решение в 2 строки. Чтение заняло больше или меньше времени, чем первое решение, которое использует больше строк кода? Как читатель, я ценю более подробное решение с циклами while.

Ответственность программиста

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

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