Comments 18
Ребёнок изобретает literate programming Кнута?
Нет, бывает ситуация, когда документацию приходится писать еще вперед кода и тестов — я называю это «разработкой в стиле флотского минера». Например, если разработчики постоянно меняются на проекте — или документация нужна чуть не больше чем код…
Но писать документацию параллельно коду с текущим состоянием ресурсов — IMHO утопия…
Понимаете, без конкретизации проекта это всё — размахивание руками.
А проекты могут разниться по частоте модификаций от верифицированной стандартной библиотеки языка С (окаменевшие остатки деятельности мамонта) до исследовательского скрипта в Jupyter, который меняется раз в час, да и компилироваться-то полностью не обязан — там могут быть какие-то куски написанные 15 минут назад с ошибками, но отложенные "на потом". Или по сложности — от зубодробительного оптимизированного под класс машин вычислительного кода до кристально понятных примеров из SICP.
И совершенно понятно, что докуменация к "коду" будет абсолютно разная в зависимости от сложности проекта, от его времени жизни, от языка проекта, от того, сколько людей будет работать с проектом, какой квалификации...
В общем, море параметров. Поэтому без хорошего системного подхода получается только чепуха.
Лично я начинаю написание сколько-нибудь сложного кода с документации. Я пихаю описание задачи в комментарий, а потом раздракониваю и поправляю его.
Пока я не знаю, как это отзовётся в будущем. Подозреваю, что лучше, чем отсутствие комментариев или комментарии, не соответствующие коду.
Вы не описываете документацию, а расписываете собственное видение решения, или, говоря другими словами, пишите презентацию, на которую будете в дальнейшем опираться при разработке, то есть, составляете план действий.
Комментарий с описанием задачи не считается документацией, даже после "раздраконивания".
Документация - по сути своей, это небольшой рассказ о вашем решении со вступлением (описание и цель решения, используемые технологии и прочее), основной частью (методы, примеры кода, ситуации использования, исключения и т.д. и т.п.) и заключением (ссылки на исходники, всякие лицензии, авторство или командная работа и тд и тп).
Вы пишете документацию, а ваш коллега не пишет. И что, за ним дописывать, тратя кучу своего времени на его задачу?
Или он пишет, но «в своём стиле», который вам вообще не нравится.
И никакой гарантии, что написанное вами будет хорошо понятно для других.
Это, кстати, хрестоматийный пример того, что комментировать надо не код — а причины, которые вызвали его появление. У меня тоже в личных программах для МК комментариев на порядок больше, чем в служебных больших системах на Java. Потому что на Java подавляющая часть кода оперирует с объектами внутри этой же системы. И там обычно нет проблем понять, зачем это сделано (и вообще проследить логику обработки).
А вот когда мы пишем определенные биты в пределы счета таймера, или включаем/выключаем ногу GPIO — это совершенно понятно с точки зрения «что мы делаем», но совершенно неочевидно «а нафига?». Потому что это включает ту часть системы, которая не представима в коде. А постоянно держать в голове еще и все аппаратное окружение (и его даташиты и проч) — нафиг-нафиг… И тут комментарии, которые поясняют причину — абсолютно необходимы.
В общем, правило простое — если разработчик средней руки может быть озадачен некоторым куском кода («зачем тут это ?», «почему именно тут ?», «можно ли его перенести ?», и т.д.) — в этом месте должен быть комментарий.
я стараюсь давать хорошие имена переменным и функциям.
Иногда это не получается и тогда пишу документацию - описание "зачем" и примеры использования. Но это в высокоуровневых языках - там это удобно, плюс - ИДЕ позволяет навигацию между определением и использованиями языковых единиц, поэтому разобраться гораздо легче, чем в низкоуровневых языках.
В низкоуровневых языках - иногда действительно комментируешь каждую строчку, потому что тут сдвиги - для маски флагов, а тут сдвиги - умножение на степень двойки, и т.д. И в регистрах постоянно - разные по сути значения, не как в памяти.
PS: надо глянуть в плагины для ИДЕ - чтобы можно было делать из комментариев ридми (или наоборот - из ридми добавлять сноски в код) и чтобы комментарии могли отслеживать - к какому коду они "привязаны" и что они устаревают (а код убегает вдаль).
Написание кода дешевле его отладки и поддержания. Поэтому документирование легко встраивается в процесс разработки. Проблема остаëтся в том, что сам факт документирования не удешевляет поддержание кода. Точно так же как и написание кода искусство документирования должно развиваться и ему нужно учиться.
Соглашусь, что в разработке этому уделяют малую часть усилий. Получается геометрическая прогрессия проблем: бизнес не умеет объяснить потребность, аналитик пишет неоднозначную документацию и тз, qa и программист интерпретируют эти задания по-разному, тест-кейсы не совпадают с кодом. В последствии вопросы поднимаются до уровня бизнеса и не решаются, пока всё не пройдут к общему знаменателю. Получается документирование даст эффект для отладки только если оно будет единым для всех уровней.
Для поддержания кода достаточно документирования на уровне разработчика. Тогда это должно происходить после готовности кода (отлажено, протестировано, принято). Документировать после каждой строчки кода - эта бездумное удорожание разработки (хотя и небольшое).
Резюмируя рассуждения, скажу, что описанное в статье документирование должно быть отдельной задачей в процессе разработки, что-то вроде тех долга. Опять же, что и насколько подробно документировать, - это бест практис, которые нужно развивать, а не внедрять ради моды.
Я какое-то время думал об этом — и вот вам аналогия с врачом. Представьте себе, что к вам (как ко врачу) приходит пациент и с порога заявляет: доктор, у меня болит то-то и то-то, анализы я сделал такие и вот такие, заключения специалистов там-то и там-то — выпишите мне в соответствие со стандартом лечения то-то и то-то, да дайте направление к физиотерапевту. Это — бизнес с ТЗ и с развитыми внутренними компетенциями — тут да, берите да дейлайте… Но так обычно не бывает. Гораздо чаще бывает по-другому:
— Либо человек приходит и жалуется что у него голова кружится (и поди-пойми от чего: может гемоглобин низкий, может курит много, может давление шалит, и т.д.) — и нужно долго и упорно разбираться, где там корневая причина или их совокупность.
— Либо человеку просто стало плохо на улице, и он вам вообще не может ничего объяснить — а просто на ногах перестал держаться: делайте что хотите!
— Либо (и это самый худший случай!) — пациент приходит, и уверенно перечисляет вам подробно симптомы, укладывающиеся в диагноз. Проблема в том, что эти симптомы — плод фантазии самого пациента, а болеет он совсем не этим…
Поэтому, когда вы имеете дело с бизнесом — вы обречены работать (особенно, поначалу!) с размытыми границами и непонятными ожиданиями. Нужна одна-две-три итерации, чтобы бизнес разобрался — что у него НА САМОМ ДЕЛЕ болит, и в каких рамках он может действовать чтобы это исправить. Я не верю, что все это можно сопровождать документацией в таких количествах, которые предложены в статье. Точнее — возможно все, но кто-то должен за это платить: лишними ставками писателей, снижением КПД программистов которые пишут документацию на 70% дублирующую код, и т.д. Я пока не вижу консенсуса в среде заказчиков, чтобы они хотели такую документацию и были бы согласны это оплатить. Наоборот, через каждого первого — все хотят удешевить процесс разработки.
Запутывающая статья, имхо. Автор тревожно смешал в одну кучу тему про комментирование деталей кода и тему про комментирование архитектуры.
Конечно, пресловутый чистый код легко прочитать и понять — в отрыве от контекста. Но, будь он даже самым чистым в мире, вы вряд ли сразу сообразите, каким образом он взаимодействует с другими частями кода, какую роль в проекте он выполняет и как использовать его в контексте.
Это вот явно про архитектуру, а не про сам чистый код как таковой.
Причём напрямую про архитектуру он тоже пишет, и заодно упирает на "почему", а не на "как":
Почему было принято именно такое архитектурное решение, почему что-то было реализовано, а что-то нет — ответы на эти вопросы не даст ни один код.
и
Вам нужно подготовить хоть какой-то документ, объясняющий, почему этот код вообще существует, почему он написан так, а не иначе, почему какие-то моменты не были реализованы, и как этот код взаимодействует с другими частями кода в контексте более широкой архитектуры.
Если оставить только про архитектуру, статья толковая. Я, например, никогда не думала в ридми добавить эти вот "почему". Упомянуть там другие варианты. Бывало, так получалось само собой. Но никакой рефлексии на этот счёт у меня раньше не было.
Пожалуй, это разумная рекомендация: вдруг выбранное решение где-то упрётся в стену. И будет проще вспомнить (перечитать), что тоже раньше рассматривалось. Выбрали самый простой вариант, например, но он с какого-то шага не позволяет развить логику глубже. И заранее были рассмотрены ещё три, и записаны. Так проще при случае сменить направление.
Но документировать код построчно, это безумно. И в целом такое вот ощущение, что это он по инерции. Если прямо детально документировать архитектуру, потом и построчно начинаешь тоже. Потом ещё - каждую букву.
Хотя в других тредах тут выше уже написали, что на достаточно низкоуровневых языках никакого самодокументирующегося кода нету, и там совет верный, даже по уровню кода. Я с такими языками никогда не работала - мои все очень уж близко напоминают английский, дойчефицированный кемел-кейсом. Такой немецкий в английских корнях. Сначала полдня за ним гоняешься, чтобы написать, потом ещё полдня, чтобы ещё что-нибудь написать, что будет выглядеть типа как комментарий. Читать потом тоже в два раза дольше.
я не увидел в статье ни примеров хорошей документации кода, ни описание инструментов автогенерации документации (html, pdf) из комментариев кода
и какой смысл такие статьи переводить или читать ?
повод для размышлений. Обычно я такой огромный код не пишу, рекорд - 230 строчек, но всё же. В будущем придётся. Возьму на заметку!
Документация - это не комментарии к коду. Документация - это руководство по эксплуатации. Когда я открываю документацию к какой-то библиотеке, я ожидаю там увидеть список функций, что они делают, что принимают на входе и что выдают на выходе. И, желательно, примеры использования. Но обычно я вижу там автоматически сгенерированную простыню, из которой непонятно ровно ничего.
Почему современная документация к коду — просто мусор. И как это исправить