Что вы должны оставить своим преемникам?

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

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

Я думаю:

• счетов / пароли
• расположение оборудования, резервных копий, компакт-дисков с программным обеспечением

Что еще?

• Аккаунты и пароли
• Информация о сервере
• Хороший код
• Документация
  • Диаграммы базы данных и объяснения удивительны
  • Список курьезов в коде
• процедуры
• Объяснение ручных процессов, или случайных, неочевидных, работ
• Список программ, которые они использовали или нашли полезными
• Контактная информация ;)

Крепкая чашка кофе и записка с извинениями.

Это то, что я хотел бы, чтобы меня оставили.

• Документация. Насколько сложно написать несколько комментариев? Построение заметок, заметок о развертывании, перемещение системных заметок. Что делать, когда перезагружаешься и все пропало.
• Документы. Напишите, почему это делается таким образом, чтобы мне не пришлось удивляться, почему вы не делаете это по-другому. Как работает система резервного копирования, как сервер реагирует на нагрузки, тестирование, контрольные примеры, варианты использования.
• Примечания. «При использовании базы данных никогда не говорите SELECT * FROM clients. Мы не уверены, почему, но она сбрасывает базу данных» .

Мой адрес электронной почты, или, возможно, даже номер телефона.

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

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

Это может быть либо внутри кода в виде комментария, либо снаружи на видном месте.

Больше, чем просто документация, я хотел бы знать, почему определенные решения были приняты, когда они были приняты. В настоящее время мы используем SWIG в проекте, и один из разработчиков хотел узнать, почему мы просто не использовали Boost :: Python. Простой ответ состоял в том, что клиент не разрешал использовать Boost в то время. Теперь другая история.

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

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

Если это настольная программа, как собрать всю систему с нуля (может быть несколько отдельных программ), как создать пакет для распространения (какие у него зависимости, например, версии .NET) и как развернуть его на серверах для загрузки, если это применимо, или запишите его на CD или DVD.

Если это веб-программа, FTP и (если применимо) SSH-доступ к серверу, а также какие инструменты используются для локального создания и тестирования кода.

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

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

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

Затем, примерно за месяц до моего отъезда, каждый раз, когда я делал что-то, что мог сделать только я , я записывал, что именно произошло, что я должен был сделать и почему. Обычно это был случай «была ошибка в компоненте xyz, чтобы исправить ее, я знал, что смотрю в файл abc из-за X, тогда мне пришлось сделать это, то и это».

Конечно, я оставил свой адрес электронной почты и номер телефона на случай, если что-нибудь придет, что они сами не смогут понять. Я получил несколько звонков в первые несколько недель, но они постепенно отвалились.

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

Правило № 1 для документации не то, что оно делает, а почему . Какова предыстория запускаемых программ и что они делают?

Я думаю, что я хотел бы видеть в документах, помимо обычного, то, что функции были опущены. Например, почему определенные идеи НЕ были реализованы или НЕ использовалась определенная платформа или метод (что в противном случае было очевидным выбором).

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

Это особенно применимо к проектам с открытым исходным кодом. Может сэкономить много времени и сил!