Методы повышения читаемости программного кода

Лекция 2 Методы повышения читаемости программного кода. Автоматизация документирования программного обеспечения. Методы повышения читаемости программного кода По различным оценкам от 40 до 70% времени разработчики программного обеспечения тратят на чтение исходного кода. Цели чтения могут разные, но неизменно преследуется цель – понять, что написано. Существует большое количество разноообразных рекомендаций к написанию исходного кода, направленных на повышение его читаемости. Причём они по большей части касаются написания именно кода, а не комментариев к нему! Рассмотрим некоторые из них. Осмысленные имена переменных Имена всех переменных, типов, файлов и функций должны быть осмысленными и не вводить в заблуждение. Имя должно верно описывать то, что оно собой представляет. Система именования должна быть последовательной и не вызывать неприятных неожиданностей. Важно следить за тем, чтобы переменная всегда использовалась только с той целью, которую предполагает ее имя. Хороший выбор имен служит, вероятно, лучшим средством избежать лишних комментариев. Имена лучше всего позволяют приблизить код к выразительности естественных языков. Разбивка кода на самостоятельные функции Подразумевается, что функциональность программы «разложена» по отдельным функциям, которые:  Имеют небольшой размер (сообразно реализованной функциональности).  Обладают минимумом побочных эффектов.  Реализованы сообразно принципу «одна функция – одно действие». Содержательные имена типов Ограничения или поведения, насколько это возможно, описываются с использованием доступных возможностей языка. Например:  При определении неизменной величины – использовать ключевое слово const.  Если переменная не должна принимать отрицательных значений – воспользоваться беззнаковым типом при её объявлении.  Применять перечисления для описания связанного набора данных.  Использовать типы в языках со статической типизаций для создания подсказок как для компилятора, так и для человека. Использовать именованные константы Вместо магических чисел в коде использовать для их хранения и применения константы, имеющие осмысленное название. Например, вместо: if (return_value == 42) {… написать так: const byte answer_on_total_question = 42; if (return_value == answer_on_total_question) {… Выделение важных фрагментов кода Для привлечения внимания читателя к отдельным участкам кода есть ряд приёмов:  Расположение объявлений в классе. Сначала должна идти информация об открытых объектах, поскольку именно она нужна пользователю класса. Закрытые детали реализации следует располагать в конце, поскольку они менее интересны большинству читателей.  По возможности стоит скрыть всю несущественную информацию.  Наоборот, не стоит прятать важный код. Лучше не писать в строке больше одного оператора и сделать этот оператор простым. Например, язык может позволять писать очень изобретательные операторы цикла for, в которых вся логика укладывается в одной строке с помощью множества запятых, но такие операторы трудно читать.  Стоит ограничить глубину вложенности условных операторов. В противном случае за нагромождением if’ов и скобок трудно заметить обработку действительно важных случаев. Объединение взаимосвязанных данных Вся связанная между собой информация должна находиться в одном месте. Например, API для каждой компоненты должен быть представлен одним файлом. Если взаимосвязанной информации оказывается слишком много, чтобы представить ее в одном месте, возможно стоит пересмотреть архитектуру кода. Если возможности языка позволяют, стоит группировать объекты программного кода с помощью языковых конструкций (пространства имён в C#, пакеты в Java, модули во многих языках). Заголовки файлов Стоит помещать в начале файла блок комментариев с описанием содержимого файла и проекта, к которому он относится. Это не требует особого труда, но приносит большую пользу. Тот, кому придется сопровождать этот файл, получит хорошее представление о том, с чем он имеет дело. Этот заголовок может иметь особое значение: большинство софтверных компаний по юридическим соображениям требует, чтобы в каждом файле с исходным кодом было заявление об авторских правах. Корректная обработка ошибок Обработка ошибок должна размещаться в наиболее подходящем контексте. Если возникает проблема чтения/записи диска, ее нужно обрабатывать в том коде, который занимается доступом к диску. Для обработки этой ошибки может потребоваться сгенерировать другую ошибку (типа исключительной ситуации «не могу загрузить файл»), передав ее на более высокий уровень. Это означает, что на каждом уровне программы ошибка должна быть точным описанием проблемы в его контексте. Странно обрабатывать ошибку, связанную со сбоем диска, в коде интерфейса пользователя. Самодокументируемый код помогает читателю понять, где возникла ошибка, что она означает и каковы ее последствия для программы в данный момент. Сообщения об ошибках так же стоит делать осмысленными не только с точки зрения пользователя, но читателя кода. Осмысленные комментарии Комментарии должны дополнять смысл того, что описано в коде. Автоматизация документирования программного обеспечения Существует целый вид программных средств, занимающих промежуточное положение между технологией грамотного (литературного) программирования (Кнут) и созданием внешних спецификаций (https://ru.wikipedia.org/wiki/Генератор_документации или https://en.wikipedia.org/wiki/Documentation_generator или https://en.wikipedia.org/wiki/Comparison_of_documentation_generators). Эти инструменты генерируют документацию из исходного кода, вытаскивая из него блоки особым образом форматированных комментариев. Пример специального формата комментариев на Java: /** * Это документация класса Widget. * Программа определяет начало комментария * с помощью особой последовательности '/**' . * * @author Имя автора * @version Номер версии */ class Widget { public: /** * Здесь документируется метод. * @param p А здесь – параметр метода. */ void method(int p); }; А это спецформат комментариев для языков C# и F#: ///

/// Это документация класса Widget. /// Программа определяет начало комментария /// с помощью особой последовательности /// и тега summary. /// Имя автора /// Номер версии ///

public class Widget { ///

/// Здесь документируется метод. ///

/// А здесь – параметр метода public void method(int p) { … } } Средство документирования анализирует все файлы вашего проекта, извлекает документацию, строит перекрестную базу данных всей извлеченной информации и выводит документ со всей этой информацией. Документировать можно практически любой код, который вы пишете: классы, типы, функции, параметры, флаги, переменные, пространства имен, пакеты и т. д. Есть средства для получения многообразных данных, которые позволяют:       Задать информацию об авторских правах. Зафиксировать дату создания. Получить информацию о перекрестных ссылках. Пометить код как устаревший. Дать синопсис для краткой справки. Описать все параметры функции Кратко рассмотрим некоторые из таких средств построения программной документации. Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java от Sun Microsystems. Javadoc — стандарт для документирования классов Java. Sandcastle — генератор документации (открытая часть некоторого внутреннего инструмента) компании Microsoft, который позволяет автоматически получить техническую документацию в стиле MSDN по заданной .NETсборке с управляемым кодом. Sandcastle состоит из набора утилит, которые получают метаинформацию из сборки, и затем рядом операций преобразуют её в конечный вид. В процессе преобразования информация представлена в формате XML, часть преобразований выполняется с помощью шаблонов XSLT. Sandcastle используется внутри Microsoft для получения документации на Visual Studio и .NET Framework. Doxygen — это кроссплатформенная система документирования исходных текстов, которая поддерживает C++, Си, Objective-C, Python, Java, IDL, PHP, C#, Фортран, VHDL и, частично, D. Doxygen генерирует документацию на основе набора исходных текстов и также может быть настроен для извлечения структуры программы из недокументированных исходных кодов. Возможно составление графов (с применением Graphviz) зависимостей программных объектов, диаграмм классов и исходных кодов с гиперссылками. Doxygen имеет встроенную поддержку генерации документации в формате HTML, LAΤΕΧ, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF.