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

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

Быстрое путешествие в прошлое

В 1830-х годах человек по имени Чарльз Бэббидж изобрел устройство, названное аналитической машиной. Аналитическая машина была побочным продуктом постоянного стремления каждого инженера к оптимизации, поскольку она была разработана во время разработки более раннего проекта, Разностной машины. Некоторые вещи никогда не меняются, верно? Инженер, осознающий во время проекта, что возможен лучший вариант проекта! Это постоянное стремление к совершенствованию и оптимизации можно увидеть у инженеров и программистов сегодня, и тогда оно ничем не отличалось. Разностная машина была высокоспециализированным математическим инструментом, в то время как конструкция аналитической машины представляла собой гораздо более универсальный компьютер. Эта заманчивая возможность обобщенных вычислений и встречный ветер проблем при создании разностной машины заставили Бэббиджа отказаться от проекта и заняться аналитической машиной. И, как это обычно бывает в современном мире, возникли проблемы с финансированием, возникли разногласия, и проект так и не был завершен. ОДНАКО дизайн проекта по-прежнему использовался в качестве основы для первых в мире компьютерных программ.

Аналитическая машина представляла собой более универсальный компьютер, способный обрабатывать «программы» на перфокартах для вычисления арифметических формул и задач. Эти перфокарты можно рассматривать как первые экземпляры исходного кода, и каждое отдельное перфорированное отверстие вносило вклад в инструкцию для компьютера, сродни функциям, ключевым словам и выражениям современных языков программирования. Теперь мы вводим в историю нового персонажа. Августа Ада Кинг, графиня Лавлейс, широко известная как Ада Лавлейс, работала над аналитической машиной и увидела истинный потенциал машины за пределами перфокарт и сложного оборудования. Она поняла, что вычисление — это больше, чем просто воспроизведение математических вычислений, но его можно использовать как средство описания более сложного набора инструкций для решения более крупных задач. Это понимание было замечено в ее заметках к Бэббиджу, где она описывает метод вычисления чисел Бернулли.

«Я хочу добавить кое-что о числах Бернулли в одну из своих заметок в качестве примера того, как неявная функция может быть обработана движком, не будучи предварительно обработанной человеческой головой и руками…»

— Ада Лавлейс Чарльзу Бэббиджу

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

«Мой дорогой Бэббидж. Я в большом смятении из-за того, что попал в такую ​​удивительную трясину и возился с этими Числами, что не могу сделать это сегодня…»

— Ада Лавлейс Чарльзу Бэббиджу

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

Мой дорогой супервизор. Я в большом смятении из-за того, что попал в такую ​​удивительную трясину и беспокоюсь об этой ошибке сегментации, что я не могу сделать это сегодня…»

Перфокарты из-за присущей им простой атомарной природы с простыми отверстиями на куске материала было очень трудно интерпретировать человеку. Вот почему Ада Лавлейс так много думала над описанием алгоритма и почему примечания были такими подробными. Она была не только первым в мире программистом, но и ярким примером разработчика, создающего отличную документацию. Пример программы, которая может быть рассчитана на аналитической машине, показан ниже.

Если присмотреться, то можно увидеть надписи на каждой из этих карт. Что это могут быть, но, возможно, одни из первых когда-либо написанных комментариев к коду?

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

Введите COBOL, или «общий бизнес-ориентированный язык». COBOL по-прежнему используется примерно в 80% сегодняшних бизнес-транзакций и был разработан для быстрого выполнения бизнес-ориентированных функций, таких как финансовые, административные функции и функции, ориентированные на данные, и с ним было легко работать. Эта концепция «легко работать» была довольно новой. Глядя на синтаксис COBOL, он использует простые английские слова для описания таких операций, как: FOR, COMPUTE, DISPLAY, PERFORM, MOVE, SUBTRACT. Это использование английских слов было преднамеренным в надежде, что люди с деловым мышлением, обладающие знаниями в предметной области, смогут получить исходный код и понять его, либо внести свой вклад в работу разработчика, либо подтвердить ее. Этот шаг к удобочитаемости получил высокую оценку в деловом мире, однако многословность языка отталкивает многих разработчиков, так как влияет на эффективность разработчиков, лаконичность программ и «шум» при просмотре кода.

С тех пор языки программирования двигались в разных направлениях. Некоторые языки подчеркивают читабельность и понимание (Visual Basic, Python, Ruby), некоторые сосредоточены на производительности (C++, Rust, Go), а некоторые просто сумасшедшие (Brainf**k, Befunge, Malbolge). Независимо от направления языка программирования, если его предполагаемой целью является широкое использование в проекте, всегда необходимо принимать во внимание удобочитаемость и понимание. Теперь мы рассмотрим некоторые методы улучшения читабельности и понимания исходного кода и, наконец, как можно сделать исходный код еще на шаг вперед и дать возможность говорить самому за себя.

Самодокументируемый код

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

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

customer_shopping_cart_item_size = 10
customer_is_currently_shopping = True
customer_checkout_successful = True
current_order_street_address_1 = "1313 Mockingbird Lane"

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

cust_cart_size = 10
cust_is_shopping = True
cust_chkout_success = True
ord_streetaddr_1 = "1313 Mockingbird Lane"

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

c_crt_sz = 10
is_c_shop = True
chk_ok = True
o_saddr1 = "1313 Mockingbird Lane"

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

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

Комментарии

Ах, часто забываемый комментарий к коду. Проклятие студентов компьютерных наук во всем мире и забытый кодовый артефакт разработчиков повсюду. Комментарии — своеобразное существо, так как они могут быть либо томами для будущего себя, либо недоделанной шуткой, пытающейся объяснить использование сложного семафора новичку-младшему разработчику. При правильном и частом использовании комментарии представляют собой «практический» источник знаний, который поможет разработчику ориентироваться в коде. Они непосредственно окружают описываемую функциональность, поэтому им автоматически предоставляется контекст и аргументация в коде. Вдобавок к этому, это первое, что разработчики пишут при разработке нового кода, поэтому они часто являются наиболее точным источником информации, когда дело доходит до понимания функциональности «голого железа».

Как видно из краткого путешествия в прошлое, комментарии существуют с самого начала программирования и встречаются с разной степенью успеха. Например, человек, только что познакомившийся с миром программирования перфокарт, скорее всего, возьмет карточку, прочитает комментарий с изображением куриной царапины на карточке и сразу же СДАВИТСЯ, пытаясь понять, что происходит. То же самое может произойти, когда вы оставляете комментарий, который может быть использован новичком-младшим разработчиком, у которого нет опыта работы с проектом. Комментарии следует использовать, когда код не является простым, но их следует использовать с осторожностью, когда функциональность может быть легко понята в коде. Например:

//The following sets the variable x to 10
x = 10

Комментарий выше бессмыслен для тех, кто читает исходный код. Любой разработчик, читающий исходный код и знакомый с синтаксисом, сразу поймет, что происходит с объявлением переменной. Тем не менее, в случае, подобном следующему, комментарии будут очень кстати:

y=[[x*100, x][x % 2 != 0] for x in range(1,11)]

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

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

Помимо исходного кода

Что, если бы код мог говорить сам за себя с небольшим количеством самодокументируемого кода и хорошо структурированными комментариями, а также с помощью дополнительного инструмента? Здесь в игру вступают генераторы документации. Генератор документации может полностью читать исходный код и извлекать определенные компоненты, выполнять статический анализ и/или вводить рукописную документацию для создания совокупности знаний, готовой к публикации и использованию другими. Генераторы документации могут быть разработаны для извлечения и документирования всех классов, существующих в проекте, существующих конечных точек API (интерфейс прикладного программирования) или зависимостей, на которые опирается программа. Эти инструменты выходят за рамки исходного кода, используя исходный код в качестве данных, чтобы помочь коду говорить самому за себя и приносить пользу разработчику, помимо простого набора инструкций.

При работе над проектом в качестве единственного разработчика может стать утомительным поддерживать проект, писать весь код, документировать функциональность и управлять развертыванием. Используя генератор документации, разработчик-одиночка может оставить рутинную работу по форматированию и обслуживанию чему-то, что создано для рутинной работы и воспроизводимости. Программа. Код становится больше, чем простая «перфокарта». Он становится артефактом, который можно использовать для получения понимания и знаний о проекте, а также многократного предоставления простой для понимания документации.

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

Что дальше?

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

Ресурсы генератора документации

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

питон

Голанг

Несколько языков

  • Спецификация OpenAPI (ранее известная как Swagger) предоставляет способ определения API. Существуют инструменты для многих языков, которые могут автоматически извлекать комментарии и исходный код для создания документа спецификации Swagger, который можно отформатировать удобным способом https://swagger.io/specification/
  • Doxygen поддерживает множество различных языков для автоматического документирования исходного кода и программ https://www.doxygen.nl/index.html.
  • Sphinx — еще один популярный инструмент для документирования исходного кода https://www.sphinx-doc.org/en/master/
  • Такие инструменты, как Sourcetail, можно использовать для более подробного ознакомления с исходным кодом и зависимостями https://www.sourcetrail.com/