Що ви повинні залишити після своїх наступників?

Припустимо, що ви єдиний розробник, який залишає роботу. Яку інформацію / матеріал, крім самого коду, слід створити та залишити для заміни?

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

Я маю на увазі:

• акаунти / паролі
• розташування обладнання, резервного копіювання, компакт-дисків із програмним забезпеченням

Що ще?

• Облікові записи та паролі
• Інформація про сервер
• Хороший код
• Документація
  • Діаграми та пояснення баз даних дивовижні
  • Список диваків у коді
• Процедури
• Пояснення ручних процесів або випадкових, неочевидних, робіт
• Список програм, які вони використовували або вважали корисними
• Контактна інформація ;)

Міцна чашка кави та вибачення.

Це те, що я хотів би, щоб я залишився.

• Документація. Наскільки важко написати кілька коментарів? Створюйте нотатки, нотатки розгортання, переміщуючи системні нотатки. Що робити при перезапуску і все пропало.
• Папери Напишіть, чому це робиться саме так, і мені не потрібно дивуватися, чому ви не робите це по-іншому. Як працює система резервного копіювання, як сервер реагує на навантаження, тестування, тестування, використовує випадки.
• Примітки. "Коли ви використовуєте базу даних, не кажіть ніколи SELECT * FROM clients. Ми не впевнені, чому вона скидає базу даних" .

Моя адреса електронної пошти чи, можливо, навіть номер телефону.

На моєму досвіді складно записати кожну деталь, тому найкраще бути доступною (певною мірою), якщо вашим наступникам потрібна більше інформації.

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

Це може бути як у коді, так і як коментар, або поза увагою.

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

Такі речі допоможуть їм не лише в розумінні проекту, але і в тому, які обмеження / обмеження / виклики подолано вашою реалізацією. Це дасть їм вихідну точку для подальшого обслуговування та розширення функцій.

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

Якщо це настільна програма, як створити всю систему з нуля (може бути декілька окремих програм), як створити пакет для розповсюдження (якими залежностями він є, наприклад, версії .NET) та як розгорнути його на сервери для завантаження, якщо це застосовується, або запишіть його на компакт-диск або DVD.

Якщо це веб-програма, FTP та (за наявності) доступ SSH до сервера та які інструменти використовуються для локального створення та тестування коду.

Якщо це вбудована система, заповніть інструкції зі створення бінарного зображення, які інструменти використовуються, як завантажувати та прошивати код у продукт, як налаштувати файлову систему на пристрої, якщо така є.

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

З точки зору нормальної документації, важливо документувати огляд всієї системи. Окремі компоненти вже задокументовані в коді, але взаємодія між компонентами і чому це робиться, або чому це потрібно поговорити з цим компонентом, є важливими, і не завжди їх легко зрозуміти просто налагодженням / переглядом коду.

Потім, приблизно за місяць до того, як я пішов, кожен раз, коли я робив щось, що тільки міг зробити, я записував саме те, що сталося, що я мав робити і чому. Зазвичай це був випадок "у компоненті xyz виникла помилка, щоб її виправити. Я знав, що шукати у файлі abc через X, тоді я повинен був зробити це, це та це".

Звичайно, я залишив свою адресу електронної пошти та номер телефону на випадок, якщо щось з’явиться, що вони не змогли зрозуміти самостійно. У перші кілька тижнів у мене було кілька дзвінків, але вони повільно відмовилися.

Ми всі хотіли б отримати повну схему потоку даних системи із переліком функціональних вимог. Більш ніж ймовірно, ви ніколи цього не отримували, коли писали систему в першу чергу! Як і в більшості місць, найкраща документація - це, мабуть, сам код, тому те, що я найбільше хотів би - це добре задокументований код. Рядки та рядки коментарів у коді, що пояснюють, що ви намагаєтеся робити як технічно, так і функціонально.

Правило №1 для документації - це не те, що вона робить, а чому . Що таке посилання на запущені програми та що вони роблять?

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

Це гарантує, що наступник завжди знає, що не робити, або якщо він більш здібний, то, можливо, він може придумати роботу і змусити певні функції.

Особливо це стосується проектів з відкритим кодом. Ви можете зекономити багато часу та сили мозку!