Я працював над проектом три місяці тому, а потім раптом з’явився ще один невідкладний проект, і мене попросили перенести свою увагу.

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

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

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

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

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

• Спостереження за якістю проекту

  цей код може використовувати деякий рефакторинг

  зробив швидку реалізацію, щоб змусити це працювати, але ABC буде кращим.

• Пункти / випуски Todo, які ви не хочете офіційно записувати в трекер випусків

  "повинен змусити цей метод працювати, x < 0але це наразі поза сферою.

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

  Наша стандартна функція сортування виконує швидке сортування, але це не зберігає порядок елементів, рівних за умовами сортування, які нам тут потрібні.

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

• Проблеми, що виникають, і те, як ви їх вирішили. На мою особисту думку, це дуже важливо: коли ви стикаєтеся з проблемою, відзначайте це у журналі.

  Перевірив код, але він дав помилку XYZ0123, виявляється, я спочатку повинен був оновити компонент C до версії 1.2 або вище.

Останні два моменти дуже важливі. Я часто стикався з подібною ситуацією чи проблемою - іноді в зовсім іншому проекті - і думав: «Хм, я пам’ятаю, витратив день на це, але що знову було рішенням?».

Повернувшись до проекту через деякий час, читання журналу проекту (будь то ваш власний чи останній розробник) повинен повернути вас у поток, який ви мали, коли ви виїжджали, та попередити вас про деякі пастки, які ви в іншому випадку можуть знову потрапити.

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

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

Редагувати :

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

Що ж тепер робити?

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

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

1. Блокуйте проміжок часу. Помістіть це у своєму календарі та витратьте час на перегляд проекту. Це може бути перегляд документації, коду, вимог тощо.
2. Прийміть, що швидкість відновлення швидко пройде. Переконайтесь, що всі учасники цього усвідомлюють. Переконайтеся, що ви це усвідомлюєте.
3. Почніть з невеликого завдання. Відбудуйте впевненість у собі, зробивши щось невелике. Якщо у вас є список нових елементів, спочатку опрацюйте більш дрібні. Це не тільки відновлює вашу впевненість, але й допомагає ознайомитись із проектом.

Як зробити це кращим для себе в майбутньому?

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

По-перше, вам потрібно мати систему для відстеження своїх тодосів. У вас зараз така система? Як ви керуєте поточною проектною роботою?

Я міг би завтра потрапити на автобус, і моя команда матиме гарне уявлення про понад 90% моїх дій. Це тому, що у мене є згуртована система документування моїх:

• Негайні тодоси (<1 тиждень пункти)
• "Приємно мати" тодоси
• Основні етапи та макротоди (де специфіка не має сенсу)
• Вимоги / конспекти зустрічей

Крім того, я використовую VCS та коментую свій код, де це доречно.

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

В чому справа?

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

Також переконайтесь, що ваші коментарі пояснюють "чому", а не просто "що" для коду. Набагато простіше читати "це виправити помилку з 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. Щойно ви закінчите зі зміною, з'єднайте її назад у свій багажник і закрийте проблему.

Є багато довгих відповідей. Це короткий опис того, що мені найбільше допомагає:

• Чистий код.
• Чистий код.
• Чистий код.
• Контроль версій (відрізняється та виконувати коментарі).
• Примітка "Пост-It" або Тодо-список або Дошка Канбана (див., Наприклад, Trello та Evernote)

Однак, Diffs, коментарі до коментарів, примітки Post-It, Todo-Lists або Kanban-Board можуть з часом неправильно трактуватися через відсутність контексту. Тож ось одне, що найважливіше:

ОЧИСТИТИ КОД.

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

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

Чи є найкращі практики?

Нижче перелічені найкращі практики, які я застосував протягом 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. Якщо ваш проект виходить за межі одного компонента і має кілька складніших розгортань до нього, не забудьте додати проектну та архітектурну документацію . Ще раз зауважте, що метою цього є спілкування структури та залежностей, а не хвилинні деталі.

На додаток до пропозицій щодо відстеження проектів, списків ToDo, Trello і т. Д., Що я прочитав один раз, що допомагає, якщо ви практикуєте TDD - це завжди відходити від свого проекту з новим невдалим тестом, який потрібно реалізувати кожного разу, коли ви повернетесь до проекту (завтра , наступного тижня чи наступного місяця)

Сядьте, зробіть «Запуск тестів» і підберіть місце, де ви зупинилися.

Окрім коментарів / списків / комітетів, важливо бути реалістичними.

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

Добре старе терпіння буде корисним.

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

Я веду щоденний журнал роботи, яку виконую. Що я робив сьогодні, що було важко сьогодні, який наступний крок, які ідеї мав сьогодні для майбутнього. Додаю також трохи розповіді про те, яким був день: чи була цікава розмова чи зустріч? Щось злість чи захоплення? Це допомагає поставити речі в перспективу, коли я згодом прочитав свій журнал.

Коли я повернувся до проекту через деякий час, я прочитав кілька останніх записів у журналі, щоб досягти швидкості з проектом. Усі ці маленькі щоденні подробиці неймовірно важливі для запам'ятовування процесу розвитку. Вони дійсно мають велику різницю в порівнянні зі списком тодо або звичайною документацією на проект, оскільки вони нагадують вам про те, як було працювати над проектом, а не тільки як користуватися продуктом.

Для мене я вважаю, що найпростішим методом відновлення проектів є лише постійний облік нотаток про вашу роботу. Я вважаю, що «OneNote» від Microsoft особливо хороший для зберігання та групування сторінок нотаток. Зокрема, панель пошуку дозволяє надзвичайно легко швидко знайти свої нотатки про щось.

Ось деякі речі, які я роблю в рамках OneNote, які допомагають мені відновити прогрес у проектах:

• Щоденні / тижневі журнали - ведіть щоденний або тижневий журнал прогресу, щоб допомогти вам зрозуміти прогрес, який ви вже зробили в проекті.

• Список завдань - у мене є загальний список справ, але я також зберігаю окремий список справ для проектів, над якими я працюю, щоб я пам’ятав, які речі я ще повинен зробити для проекту. Я іноді також залишаю // TODO: елементи мого коду.

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

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

Для простих проектів я роблю це:

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