Независимо от того, насколько хороши ваши навыки программироания, написание документации определяет, насколько эффективно будущие члены команды могут работать с вашим кодом. Помните, что вы пишете документацию для будущих разработчиков.
- Заголовочные комментарии к функциям и методам
Доступные сегодня IDE могут автоматически генерировать комментарии к функциям и заголовкам методов. Эти комментарии могут быть преобразованы в документацию по коду. Полезно их улучшить, добавив дополнительную информацию. Однако, имен и типов должно быть достаточно, чтобы понять, что делает функция. - Документация по продукту
Документация по продукту не совсем техническая, но это то, что вы должны написать и поддерживать. Она содержит список всех возможностей, предоставляемых вашим программным обеспечением, и как оно работает. Всякий раз, когда вы разрабатываете что-то новое, вы должны немедленно обновлять его в документации к продукту. - Технические схемы
Схема – это визуальное представление сложных решений. Она должна быть легкой для понимания без необходимости какого-либо другого текста. Рекомендуется написать программу, объясняющую, как читать техническую схему, чтобы убедиться, что все понимают одно и то же. Существует множество схем, которые могут быть полезны. Схемы баз данных полезны для быстрого понимания связи между многими сущностями. Схемы архитектуры ПО используются для объяснения того, как различные части ПО взаимодействуют друг с другом. Схема последовательности отображает последовательные этапы сложного потока. - Журнал технического проектирования
Это самая важная часть документации. Большинство разработчиков не тратят время на ее сопровождение. Вам необходимо написать короткое предложение, объясняющее контекст и ограничения, с которыми вы столкнулись при принятии этого решения. Помните, что код не вечен. Если вы просто объясните контекст журнала проектирования, то следующий разработчик сможет его понять и принять правильное решение с новым контекстом.