Как сделать большую кодовую базу проще для понимания

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

Идея заключается в том, чтобы объяснить в терминах непрофессионала, как работает конкретный класс (и не только почему, как это делает большинство комментариев). Другими словами, чтобы дать коллегам-программистам другой взгляд на то, как работает класс.

Например:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

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

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

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

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

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

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

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

При этом документация должна оставаться СУХОЙ, то есть не повторять информацию, которая могла бы быть выражена в коде или уже была описана в другом месте (фразы типа «как состояния документации» являются предупреждающим знаком). В частности, будущие сопровождающие будут достаточно хорошо владеть языком программирования проекта, как и английский; Перефразирование реализации в комментариях (что я вижу слишком часто, когда люди гордятся своей документацией) не имеет никакой пользы и может отклониться от реализации, в частности, если документация не соответствует описываемому ею коду.

Наконец, структура документации должна быть стандартизирована по всему проекту, чтобы каждый мог ее найти (это беспорядочный беспорядок в документах Питера в трекере ошибок, Сью в вики, Алане в readme и Джоне в исходном коде ...) ,

Я не согласен, что это очень хороший подход, в основном из-за

1. Когда вы реорганизуете свой проект, перемещаете методы, документация разрывается.

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

Если у вас есть модульные тесты для каждого метода / интеграционные тесты для каждого модуля, это будет самостоятельная документация, более понятная и понятная по сравнению с комментариями кода.

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

Я лично являюсь поклонником высокоуровневого проектного документа - желательно написанного ДО какого-либо кода - который дает обзор дизайна и список классов и ресурсов. Нисходящий дизайн значительно упрощает вещи - ваш может быть "игровой движок -> аппаратные средства -> контроллеры -> джойстик"; таким образом, новый программист сказал, что «исправить кнопку« a »на контроллере xyz», по крайней мере, будет знать, с чего начать.

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

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

Вещи для включения в проектную документацию:

• Архитектура приложения
• Структура логического кода
• Потоки данных
• Ключевые используемые модели и мотивы их использования
• Структура исходного кода
• Как его построить (это дает представление о неявных зависимостях и физической структуре исходного кода)

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

• Предпосылками
• Последствия
• Инварианты
• Исключительные условия (броски)

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

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

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

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

Подобно тому, что сказал @meriton, разбейте код на отдельные компоненты. Еще лучше разбить кодовую базу на отдельные пакеты (JAR-файлы, гемы, яйца и т. Д.), Чтобы сделать еще более понятным разделение компонентов. Если есть ошибка, разработчик должен только найти пакет, в котором есть ошибка, и (надеюсь) только исправить это там. Не говоря уже о том, что проще проводить модульное тестирование, и вы можете воспользоваться преимуществами управления зависимостями.

Другое решение: уменьшить кодовую базу. Чем меньше кода, тем легче его понять. Рефакторинг неиспользованного или дублированного кода. Используйте методы декларативного программирования . Конечно, это требует усилий, и часто это невозможно или практически невозможно. Но это достойная цель. Как писал Джефф Этвуд: «Лучший код - это вообще не код»

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

Например, игровой движок, как правило, довольно сложен, и трудно определить, что называется после сотен слоев абстракции. Возможно, стоит создать файл наподобие «Architecture.txt», чтобы объяснить, как и почему код структурирован таким образом, и почему существует этот бессмысленно выглядящий уровень абстракции.

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

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