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

С завтрашнего дня я вернусь к старому проекту. Я понимаю, что я не помню, что именно я делал. Я не знаю с чего начать.

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

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

Конечно, есть очевидные кандидаты, такие как списки задач и журналы выдачи; Рассмотрение недавно добавленных проблем должно дать вам представление о том, что вы делали, когда уходили из проекта.

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

• Наблюдения за качеством проекта

  этот код может использовать рефакторинг

  сделал быструю реализацию, чтобы заставить это работать, но ABC будет лучше.

• Элементы / проблемы Todo, которые вы не хотели бы официально регистрировать в системе отслеживания проблем

  "должен заставить этот метод работать, x < 0но это в настоящее время выходит за рамки.

• Дизайнерские решения - особенно нетривиальные.

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

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

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

  Извлек код, но он выдал ошибку XYZ0123, оказывается, мне сначала пришлось обновить компонент C до версии 1.2 или выше.

Последние два пункта очень важны. Я часто сталкивался с похожей ситуацией или проблемой - иногда в совершенно другом проекте - и думал: «Хм, я помню, как потратил на это день, но какое снова было решение?»

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

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

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

Редактировать :

Я должен отметить, что списки дел (списки дел с определенными приоритетами, разделенные по месту проведения и проекту) являются ключевой частью книги Getting Things Done , которую я нашел очень влиятельной.

Что делать сейчас?

Теперь с завтрашнего дня я вернусь к своему старому проекту и пойму, что не помню, чем именно занимался и с чего начать!

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

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

Как сделать это лучше для себя в будущем?

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

Во-первых, вам нужна система для отслеживания ваших задач. У вас есть такая система сейчас? Как вы управляете текущей работой над проектом?

Завтра меня может сбить автобус, и моя команда будет иметь представление о более чем 90% моих предметов. Это потому, что у меня есть целостная система для документирования:

• Немедленные задачи (<1 неделя)
• "Приятно иметь" задачи
• Вехи и макро-задачи (где детали не имеют смысла)
• Требования / заметки о встрече

Кроме того, я использую VCS и комментирую свой код там, где это необходимо.

Это работает для меня и моей команды, так как я являюсь основным разработчиком. Вы можете использовать какую-то систему отслеживания проблем для команды. Или отставание при работе с Agile. Есть множество вариантов. Если вы действительно заинтересованы в этом, ознакомьтесь с документом Getting Things Done или другими соответствующими методологиями управления задачами, которые существуют почти точно благодаря тому, что вы описываете.

В чем смысл?

Специфика системы менее актуальна, чем то, что это единая система и вы ее используете . И это ты используешь. И использовать это. Это важно. Более важно, чем хорошая совершенная система, которую вы не используете. Не делайте «хорошо, большая часть моей работы здесь, но некоторые в моей голове», иначе вы не будете возненавидеть себя, возвращаясь к проекту.

Кроме того, убедитесь, что ваши комментарии объясняют «почему», а не просто «что» для кода. Гораздо проще прочитать «это исправить ошибку в IE8» и вспомнить, что делает код, чем просто пояснить технические детали.

По моему мнению, «возобновление» проекта кода состоит из двух частей:

1. Определить, где вы остановились
2. Вспоминая, что осталось сделать

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

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

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

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

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

1. Ни одна задача не является слишком рано или слишком маленькой, чтобы записать

Люди обычно составляют списки TODO для того, что они планируют делать в будущем , но поскольку программирование требует концентрации, и поскольку мы можем быть прерваны в любое время , я считаю полезным записать даже то, что я делаю сейчас, или что я собираюсь начать в считанные секунды . Вы можете чувствовать, что находитесь в зоне, и вы не можете забыть решение, которое просто поразило вас в тот ага момент, но когда ваш коллега заглядывает к вашему кубу, чтобы показать вам фотографию его зараженного пальца , и вы только в состоянии наконец избавиться от него, начав грызть собственную руку , вы можете пожелать, чтобы вы записали быструю заметку, даже если только на заметку Post-It ™.

Конечно, может быть лучше другой более устойчивый носитель (особенно мне нравится OmniFocus ), но суть в том, чтобы хотя бы где-то его иметь , даже если вы закончите через 20 минут, а затем выбросите Post-It ™. Хотя вы можете обнаружить, что эта информация становится полезной, ставить клиенту табели учета рабочего времени или счета, или когда ваш начальник / клиент спрашивает вас, над чем вы работали, и вы не можете вспомнить. Если вы поместите все эти заметки в ящик, ящик или папку, то, когда произойдет большое прерывание - прерывающий проект, - вы сможете просмотреть их и вспомнить многое из того, что вы сделали, чтобы привести свой код к точке, в которой вы найти его, когда вы вернетесь к проекту.

2. Используйте доску на своем столе, чтобы запечатлеть идеи с большими картинками

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

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

Я думаю, что лучше с ручкой в ​​руке, так что выкидывание мыслей на белую поверхность естественно для меня, но если вы не находите, что это так, вот некоторые вопросы, которые могут помочь вам решить, что имеет значение :

• Если бы я был ведущим разработчиком, собирался отправиться в свадебное путешествие на 3 месяца, пока другие разработчики завершили проект, какое общее направление я бы хотел им дать? О каких идеях я хотел бы знать, чтобы они знали, или о подходах, которые я хотел бы использовать? Какие библиотеки или другие полезные решения я бы хотел, чтобы они знали?
• Если бы этот проект был моей идеей на миллион долларов, которая, как я знал, обеспечила бы мою будущую финансовую независимость, но я был намечен на критическую операцию, которая вывела бы меня из строя на 3 месяца, что бы я хотел, чтобы моя будущая личность имела, чтобы обеспечить успешное завершение проект?

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

Я рекомендую потратить деньги, чтобы купить приличную доску размером не менее 3 х 4 и повесить ее в том месте, где вы обычно работаете. Есть много преимуществ физической доски по сравнению с любой виртуальной системой.

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

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

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

3. Информировать заинтересованные стороны о стоимости прерывания проекта

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

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

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

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

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

Короче говоря:

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

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

Использование системы контроля версий с правильными стратегиями ветвления и слияния в сочетании с системами отслеживания проблем (такими как Redmine или GitHub ) поможет вам разделить внесенные изменения, дать им направление и документировать отсутствующий «контекст» как естественная часть рабочего процесса.

1. Прежде чем приступить к изменению кода, убедитесь, что в вашей системе отслеживания ошибок есть «проблема». Это покрывает недостающую часть «что я делал» в вашей работе.
2. Создайте ветку в вашей системе контроля версий и убедитесь, что ваши изменения в этой ветке связаны ТОЛЬКО с вышеупомянутой проблемой. Это поможет вам изолировать изменения и даст вам историю изменений, ответив на вопрос "где я остановился?" как только вы вернетесь к работе позже.
3. Как только вы закончите с изменением, объедините его обратно в ваш ствол и закройте проблему.

Там много длинных ответов. Это кратко о том, что помогает мне больше всего:

• Чистый код.
• Чистый код.
• Чистый код.
• Контроль версий (различия и комментирование).
• Post-It note или Todo-List или Kanban-Board (см., Например, Trello и Evernote)

Однако из-за отсутствия контекста со временем могут быть неверно истолкованы сообщения «Различия», «Комментарии», «Записки», «Списки Todo» или «Канбан». Итак, вот одна вещь, которая является наиболее важной:

ЧИСТЫЙ КОД.

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

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

Есть ли лучшие практики?

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

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

2. Модульный код (в зависимости от языка и среды программирования, используйте классы, модули, пакеты, компоненты).

3. Документируйте свой код. Это включает в себя сводную документацию в верхней части каждого файла (что это делает? Почему? Как его использовать?) И конкретные комментарии на уровне функций, процедур, классов и методов (что это делает? Аргументы и возвращаемые значения / виды «побочные эффекты»).

4. Добавить TODOи FIXMEкомментарии, пока вы кодируете. Это помогает запомнить причину и причину, которые неизбежно войдут в вашу кодовую базу и что в дальнейшем вы будете спрашивать WTF ?! , Например:

   //TODO shall actually compute X and return it
   ... some code that does not compute X yet (maybe returns a fixed value instead)
   
   //FIXME make this constant time instead of n^2 as it is now 
   ... some code that works but is not efficient yet
   

5. Привыкайте рисовать диаграммы для документирования структуры и сложного поведения, такого как последовательности вызовов между модулями / объектами / системами и т. Д. Лично я предпочитаю UMLet, поскольку он быстр в использовании, создает приятную графику и, что самое важное, не мешает вам , Но, конечно, вы должны использовать любой инструмент для рисования, который вы найдете, делает работу. Помните, что целью любого такого рисунка является краткое сообщение, а не указание системы в мельчайших деталях (!!).

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

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

8. Возьмите за привычку автоматизировать повторяющиеся задачи . Например, циклы компиляции / сборки / тестирования должны быть написаны в какой-либо форме (например, при использовании JavaScript grunt, в Python fabric, в Java Maven). Это поможет вам быстро набрать скорость, когда вы вернетесь.

9. По мере роста вашего проекта добавляйте больше документации, генерируя документы с исходным кодом (используя некоторую форму комментариев в стиле JavaDoc и соответствующий инструмент для создания из него HTML или PDF).

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

В дополнение к предложениям по отслеживанию проекта, спискам задач, Trello и т. Д., Что я однажды прочитал, и это помогает вам, если вы практикуете TDD, всегда отойти от своего проекта с новым провальным тестом, который можно реализовать всякий раз, когда вы возвращаетесь в проект (завтра , на следующей неделе или в следующем месяце)

Сядьте, выполните «Выполнить тесты» и возьмите, где остановились.

В дополнение к комментариям / спискам дел / коммитам, важно быть реалистичным.

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

Старое доброе терпение будет полезно.

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

Я веду ежедневный журнал своей работы. Что я делал сегодня, что было сложно сегодня, каков следующий шаг, какие идеи у меня были сегодня на будущее. Я также добавляю немного повествования о том, как прошел день: была ли интересная беседа или встреча? Что-то злило или восхищало? Это помогает понять ситуацию, когда я позже прочитаю свой журнал.

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

Для меня я считаю, что самый простой способ возобновления проектов - это просто вести постоянный учет заметок о вашей работе. Я считаю, что Microsoft OneNote особенно хорош для хранения и группировки страниц заметок. В частности, панель поиска позволяет очень легко быстро найти ваши заметки по чему-либо.

Вот некоторые вещи, которые я делаю в OneNote, которые помогают мне возобновить работу над проектами:

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

• Список дел - у меня есть общий список дел, но я также держу отдельный список дел для проектов, над которыми я работаю, чтобы я помнил, что еще предстоит сделать для проекта. Иногда я также оставляю // TODO: элементы в моем коде.

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

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

Для простых проектов я делаю это:

1. Простой файл README в корневом каталоге (который, следовательно, также будет в конечном итоге в управлении версиями), где я отмечаю все, что всплывает при разработке: что делать, ошибки, улучшения / идеи. Это первый файл, который я прочитаю, если мне придется отложить проект на задний план.
2. Комментарии TODO / FIXME / XXX
3. Я также часто использую ToDoList