Стратегии документировать + комментировать задним числом

Question

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

Теперь мне нужно сосредоточиться на нетехнических аспектах моего бизнеса и передать этого гиганта команде разработчиков для обслуживания и новых функций. Итак, что я могу сделать ... какие наиболее полезные комментарии / документацию написать? Какова лучшая стратегия для обратной документации? (Есть книги на эту тему?)

PS. Спасибо за ваши месяцы и месяцы помощи Stack Overflow. Я едва знал HTML год назад. Вы прошли через все это!

Answer 1

1. 70K строк не так уж много.Он может быть больше, чем проекты, над которыми вы обычно работаете, но, по крайней мере, он не настолько велик, что один человек не может понять большинство из них.Это, вероятно, то, что привело вас к неприятностям в первую очередь.Вам не помешает пройтись по каждому файлу и написать несколько предложений о том, что делает класс.

2. 70K строк слишком велико, чтобы навязывать кому-то или какой-либо команде безкакое-то объяснение того, что он делает и почему.Пожалейте своих бедных подчиненных (и сократите трудозатраты, которые они потратят на то, чтобы поцарапать свои бедные головы), по крайней мере, написав дорожную карту, в которой подробно объясняется, что делает проект, как он организован, какие части важны для производительности илидля удовлетворения требований, какие части нуждаются в работе.Если у вас есть какие-либо письменные требования к проекту, они должны быть включены.

3. Я бы подумал, что прежде чем вы заставите свою команду работать над этой незарегистрированной кучей кода, вы планируете хотя бы выполнитьостроумие членов команды на один день и дать им ориентир.Запишите все, что вы хотели бы сказать им во время этой ориентации.Дайте команде этот документ и некоторое время, чтобы прочитать его, прежде чем вы действительно встретитесь с ними.Теперь вы можете использовать этот день для уточнения документа, отвечая на их вопросы.Убедитесь, что ответы включены в следующую редакцию документа.Пусть первая задача вашей команды - решить проблему, которую вы создали.Это поможет им подготовиться к тому моменту, когда они начнут внедрять новые функции.

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

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

Answer 2

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

1. Обязательные параметры
2. Возвращаемые значения
3. Объяснение функции

Лучше всего делать, когдакомментировать - думать о том, что произойдет, если вы внезапно исчезли и не смогли объяснить свой код.Что бы разработчик, который взял на себя ответственность, должен знать и понимать.Очевидно, что вы не должны были делать свой код слишком абстрактным (иначе говоря, использовать только имена переменных, такие как $ x, $ y, $ z, если не уместно).