Нормально / приемлемо записывать заметки, мысли, алгоритмы, решения при кодировании и обслуживании? [закрыто]

22

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

Итак, это нормально и приемлемо, что я записываю свои мысли и решения в какой-то файл Notepad ++ во время кодирования?

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

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

Мистеру
источник
5
Я тоже склонен это делать и вообще сожалею об этом, когда я этого не делаю. Очень полезно иметь что-то, на что можно оглянуться позже, чтобы вспомнить, почему вы сделали что-то определенным образом, или иметь возможность принять решение позже, когда вы не будете вдаваться в это с помощью туннельного зрения. Когда я забываю записать что-то, я обычно забываю почему, а затем трачу больше времени на пересмотр моих шагов.
ПсевдоПсихе
21
Я чувствую, что мы пропускаем часть контекста? Было ли это наблюдение сделано вокруг жалобы на эффективность? Часто критика сопровождается предположением о коренной причине, которая может иметь или не иметь отношение к делу.
Джим Раш
9
«Комментарии и документация» должны быть записаны в исходный код и сохранены. Ваши мысли о рассмотрении вариантов дизайна могут быть записаны, но, как правило, не сохранены, то есть вещи, которые редко помогут вам позже (вы можете вести записи о результатах этого процесса мышления, если это не ясно из самого исходного кода, но это не то, о чем вы спрашивали). Если вы предпочитаете электронную форму, форму карандаша и бумаги или если вы можете делать все это в своей голове, решать только вам, никто другой, кроме вас, может сказать вам, что работает лучше для вас.
Док Браун
4
... PS: я обычно предпочитаю карандаш и бумагу или белую доску для этого материала, и я думаю, что я не стал бы лучшим программистом, если бы попытался сделать все это в моей голове, как раз наоборот.
Док Браун
7
Почему это не приемлемо? Приемлемо для кого?
Пол Д. Уэйт

Ответы:

62

Это не только нормально, но и хорошая идея.

Там есть известная цитата

«Дайте мне шесть часов, чтобы срубить дерево, и я проведу первые четыре заточки топора».

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

Дэн Пичельман
источник
8
Это хорошая цитата, хотя я бы убрал ошибочную атрибуцию. quoteinvestigator.com/tag/abraham-lincoln
Пол Дрейпер,
1
Конечно, верное утверждение и хорошая цитата, но, насколько я понимаю, вопрос имеет другую направленность. Насколько я понимаю, ФП не сомневается в важности предварительного планирования. Он спрашивает, эффективнее ли записывать эти мысли / планы или просто держать их все только в своей голове.
Док Браун
2
Считаю, что час заточки более чем достаточно. Эта задача должна была быть оценена максимум в 3 часа, но слабость была потрачена на бессмысленную переподготовку. Что было моральным снова? ;-)
Стив Джессоп
26

Да, это вполне приемлемо и нормально.

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

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

mcknz
источник
4
Я настоятельно рекомендую не включать в исходный код заметки о рассмотрении вариантов дизайна и попытках сделать суждение в качестве комментариев, они никогда не бывают «достаточно короткими». Только окончательные результаты этого мыслительного процесса, но это сильно отличается от того, о чем спрашивал ОП.
Док Браун
3
Я часто нахожусь в дискуссиях на тему «почему мы приняли это решение». Невероятно полезно вернуться к моим ежедневным заметкам о проекте, чтобы предоставить контекст, в том числе альтернативы, которые мы обсуждали. Я думаю, что я в хорошей компании: в соответствии с The Everything Store Джефф Безос делает то же самое.
kdgregory
8
@DocBrown - иногда полезно указать причины, по которым вы не использовали другие возможные методы / алгоритмы, чтобы будущий разработчик не пытался заменить то, что вы сделали
HorusKol
1
@HorusKol: конечно, в некоторых редких случаях это банальный здравый смысл. Но это сильно отличается от «документирования процесса принятия решений» .
Док Браун
1
@ Док право, я не думаю, что кому-то нужны страницы заметок в их исходном коде. :)
mcknz
20

Это чертовски хорошая идея. Прямо до тех пор, пока это не станет способом откладывать.

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

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

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

candied_orange
источник
Уценка это еще один отличный способ сделать эти заметки. Держите руки на клавиатуре, чтобы процесс мышления был минимальным.
RubberDuck
1
Будь то работа с редактором или захват ручки или салфетки - лучшая альтернатива, полностью зависит от ваших личных навыков набора текста и рукописного ввода. Для меня лучшим решением является редактор.
cmaster - восстановить монику
9

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

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

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

Для менее формальной документации я на 110% согласен с предыдущими замечаниями по поводу встроенных комментариев. Это единственный путь; так или иначе, все остальное в конечном итоге теряется. Но аккуратные и вдумчивые встроенные комментарии - это отдельный навык кодирования, разработанный с помощью усилий и практики, как и любой другой навык. Вы можете увидеть некоторые из моих (очень) старых вещей, например, здесь . Этот стиль может или не может понравиться вам. Я бы порекомендовал сначала найти хорошо прокомментированный код в стиле, который вам нравится, и эмулировать его в своем собственном коде. Через некоторое время адаптируйте его так, как считаете нужным.

Джон Форкош
источник
4

Отличное место для размещения такого рода информации - это сообщение коммита вашей системы контроля версий (SVN, git и т. Д.). Таким образом, вы можете увидеть изменения и их обоснование в одном месте.

Дерек
источник
1
Это также делает их доступными для поиска. Вы можете искать сообщения коммитов в командной строке git и sourcetree, например. Если вы просто используете блокнот, скорее всего, файлы никогда не откроются снова, и их будет сложно найти, не зная какого-то обширного bash и написания скрипта, который ищет все соответствующие места.
Надеюсь,
Я пытаюсь сделать это как в моих утверждениях commit, так и в запросе об ошибке или функции со ссылками на commit. Я также делаю датированные встроенные комментарии в коде с причинами, по которым я изменил код. Это очень помогает в нашей скрипучей старой базе кода, где комментарии в основном неизвестны.
delliottg
Нет, это что-то еще. Сообщения коммита должны описывать, что было сделано, а не почему. Почему в вашей документации документируются комментарии к коду, сопроводительная документация и решение проблем с трекером. Вы не можете помещать пять страниц заметок и проектных работ в сообщение о коммите, и не должны этого делать.
Легкость гонок с Моникой
Замечательно поставить его в систему контроля версий. Лучшее место - простой текстовый файл внутри. Это легче использовать, чем фиксировать сообщения.
Турбьёрн Равн Андерсен
2

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

Ясность в формулировании того, что я пытаюсь сделать, помогает мне осознать предположения, предположения и / или требования, которые не обязательно выполняются.

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

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

Эрик Эйдт
источник
1

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

Это также не должно занимать какое-то время. Если вы тратите время на размышления, вы можете записать свои мысли от 1 до 1 (при условии, что они будут / могут быть кому-то полезны).

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

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

HopefullyHelpful
источник
1

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

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

gnasher729
источник
1

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

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

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

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

Карл Билефельдт
источник
1
TDD - это занятие по ведению заметок? Я так не думаю.
Роберт Харви