Передача моего собственного проекта на ком-то еще - что сделать? [закрытый]

Документация - это одно, а донести ее до головы нового владельца проекта - другое. IMHO это типичная ситуация, когда "меньше значит больше" - чем меньше документации придется прочитать вашему коллеге, чтобы что-то понять, тем лучше. И, конечно, обучение требует времени - для вас обоих, примите это.

Итак,

• вместо того, чтобы писать много документации, сделайте ваш код самокомментирующимся

• храните все документы / исходный код и т.д. в чистой и хорошо названной структуре папок

• убедитесь, что ваш процесс сборки почти полностью автоматический

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

• чистота, чистота, чистота!

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

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

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

Я думаю, что большинства проблем можно избежать с помощью всего двух простых правил.

1. Сохраняйте код в соответствии с руководством по стилю платформы.
2. Именование, именование и именование.

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

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

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

I think for a situation like this the most important thing is a working, complete build that automatically compiles, documents, and tests the project. Таким образом, существует четко определенная точка, в которой у нового разработчика все работает. Затем он сможет разобраться с тестами и документацией, в принципе.

новый владелец жалуется на ужасную документацию, ошибки и плохой дизайн.

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

Затем первоначального владельца месяцами беспокоят вопросы о проекте, просьбы исправить старые ошибки и т. Д.

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

Это проект среднего размера,

«Средний» по сравнению с чем? Сколько строк или кода, сколько файлов, сколько мегабайт кода?

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

Я бы поступил так:

1. Сначала просканирую весь код и:
   1.1 Удалите все закомментированные блоки кода.
   1.2 Удалите все неиспользуемые подпрограммы и классы (я говорю о «забытых» подпрограммах, а не о частях служебной библиотеки).
   1.3. Убедитесь, что весь код соответствует единым правилам форматирования. Т.е. не следует смешивать class_a , ClassA и CClassA в одном приложении, не следует использовать разные стили для скобок и т. д.
   1.4 Убедитесь, что все имена (класс, переменная, функция) говорят сами за себя. Ваш код должен быть как можно более понятным - это избавит вас от написания слишком большого количества документации.
   1.5 В ситуациях, когда есть сложная или трудная для понимания функция, пишите комментарии. Делайте их как можно короче и публикуйте только тогда, когда они абсолютно необходимы.
   1.6 Постарайтесь убедиться, что не осталось известных ошибок. Если есть известные ошибки, задокументируйте их и их поведение.
   1.7 Удалите мусор из каталогов проекта (файлов, которые не используются в проекте и т. Д.)
   1.8 Если возможно, убедитесь, что код по-прежнему компилируется и работает должным образом.
2. Создавайте html-документацию с помощью doxygen. Просмотрите его несколько раз, немного измените комментарии к коду, пока не будете удовлетворены. Или пока вы не будете удовлетворены результатом. Не пропускай этот шаг.
3. Если существует репозиторий управления версиями (скажем, репозиторий git) со всей историей разработки, передайте его новому сопровождающему или дайте ему (ей?) Функциональную копию репозитория. Это будет полезно для (git) разделения пополам и поиска источника ошибок.

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