Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті
Господа, можно провести небольшой опрос, по поволду вброса gaperton: gaperton.livejournal.com/32772.html
Как у вас в проектах обстоят дела с проектной документацией?
Количество и качество документации в любом случае оплачивает заказчик. Он может не проконтролировать, тут уж на совести.
Мосье наверное не представляет, что бывают бизнесы, работающие на открытый рынок, без заказчика. И даже то, что таких бизнесов большинство.
2 eugene_n. У мосье пиписька самая большая -это понятно, всё-таки «mission critical». Сорри за оффтоп.
eugene_n, один-в-один мои мысли по этой статье.
Аналогия с самолетом хорошая: -)
Знову за рибу гроші...Можно сокрушаться по поводу отсутствия мифической и всегда актуальной документации
Я понимаю о чем вы — когда 15 лет бегаешь латаешь и подмазываешь один и тот же софт, через некоторое время знаешь его наизусть. Только извините мосье — то чем вы занимаетесь, не инженерия, а кустарничество. Собственно как и у всей банковско/бизнесовой обслуги у вас крайне заужен кругозор, вы просто не представляете, что такое десятки клонов построенных на одной платформе, что такое жесткое соблюдение промышленных стандартов и наконец, что такое mission critical, где каждая бага может стоить жизни. Так что не обощайте пожалуйста и не обобщаемы будете.
Тем не менее, суровая правда жизни в том, что чем больше проект, тем меньше вероятность, что вы найдете по нему вменяемую документацию.
Все равно вы понятия не имеете как писать эту “документацию”, о которой вы говорите, и поддерживать ее в актуальном виде. Зачем же ожидать этого от ваших предшественников. Странно право. Делайте лучше нормально то, что вы можете и _должны_ уметь делать.
Ну, трохи довго-нудно, але десь так приблизно.
Всего должно быть в меру — и документации тоже.
Я вообще писал в рассказе про вполне конкретную разработку
Было бы неплохо явно указать это. Потому что на волне этой публикации поднялась целая волна кричащих — долой документацию! Real programmers don’t have time to doc code! etc.
Я могу сказать одно — сейчас без документации ОЧЕНЬ хреново (мягко выражаясь)!
Знаете, в вашем рассказе это не очень конкретно написано. «Документация по коду».
Ну вот и разобрались что к чему.Я вообще писал в рассказе про вполне конкретную разработку, с конкретными признаками.
А за статью спасибо, хоорошо написана.
Кто бы спорил? Только не надо экстраполировать это на любую разработку.
Так и не экстраполируйте это на любую разработку. Кто заставляет-то? Я вообще писал в рассказе про вполне конкретную разработку, с конкретными признаками. Размер — большой. Возраст — большой. Людей — десятки, но меньше сотни. Развивается одновременно с поддержкой.
Кто бы спорил? Только не надо экстраполировать это на любую разработку.А вот в случае с внутренним продуктом, когда количество пользователей фреймворка составляет десятки человек, и они меняются редко — семинарские занятия будут эффективнее
2 rssh +1
К тому же, честно говоря я не вижу принципиальных преимуществ в передаче знаний Design Principles в виде документа, перед передачей этих же знаний в виде лекции-семинара. Скажем так, в случае с ядром Linux — понятно что эти преимущества есть. А вот в случае с внутренним продуктом, когда количество пользователей фреймворка составляет десятки человек, и они меняются редко — семинарские занятия будут эффективнее, хотя бы из-за наличия обратной связи при обучении. Очная форма обучения лучше и качественнее, чем заочная, с этим, я думаю, многие согласятся. Хотя, документировать Design Principles как минимум не вредно, и скорее полезно, даже в этих случаях, что тут говорить.
Только Вам это кажеться отсуствием документации, а мне наличием:)
MSDN это не «внутренняя документация», а «внешняя». А речь о внутренней. С какой стати мне это узнавать? Мне это не интересно, хотите — узнавайте.
А то, что надо знать как устроены драйверы в Linux вообще, и как они программируются — конечно надо, только это знание само по себе никак не поможет дать ответы на вопросы, которые я привел. Это так называемые Common Design Pronciples для написания драйверов, помогающие его читать и писать, и ни в коей мере не являются «документацией по коду».
Как раз по API ядра Линукса документации есть довольно много:
www.tldp.org/...html/index.html
(это что, обоим спорящим было лень спросить у гугля?)
// ну и понятно что там она нужна, так как это public API, для сторонних разработчиков, которых много.
gaperton 11 час. назад
А можно где-то что-то по поводу програмерской документации почитать? Что там должно быть, чего там быть не должно, есть ли какой-то open-source проект с выложенной «правильной» документацией?Я знаю один мега-успешный opensource проект. Ядро Linux. Вероятно, должен быть эталоном.:) Должно быть, Вам не составит труда найти по нему актуальную документацию?:) Например — простая задача. Вам надо добавить драйвер нового контроллера NAND-Flash. Или же, драйвер аппаратного криптоускорителя. Я понимаю, доку будет найти непросто — так Вы попросите местных специалистов по документации Вам помочь ее найти. Ну, или объяснить, что же Вам в конце концов делать, если это не получится. Потом, интересно будет послушать их мнение, почему же такие best practices не исполняются, если они реально best. Ядром Linux, все-таки занимаются не идиоты, или нет?
Хорошая документация увеличивает цену проекта в 5 раз (вот вам и все «лучшие практики», дело в цене). Узнайте сколько MS тратит на поддержку MSDN в актуальном состоянии.
Например — простая задача. Вам надо добавить драйвер нового контроллера NAND-Flash.
Я думаю для человека с нуля таки придеться прочитать пару док — для теории что-н типа «Essential Linux driver development» или «Professional Linux Kernel Architecture», а для практики даташиты на используемые микросхемы. Нет конечно можно попытаться экстраполировать отдельно взятый драйвер HDD на все блочные устройства, а карту регистров снять методом тыка, но далеко ли на этом уедешь?
Я знаю один мега-успешный opensource проект. Ядро Linux. Вероятно, должен быть эталоном.:) Должно быть, Вам не составит труда найти по нему актуальную документацию?:) Например — простая задача. Вам надо добавить драйвер нового контроллера NAND-Flash. Или же, драйвер аппаратного криптоускорителя. Я понимаю, доку будет найти непросто — так Вы попросите местных специалистов по документации Вам помочь ее найти. Ну, или объяснить, что же Вам в конце концов делать, если это не получится. Потом, интересно будет послушать их мнение, почему же такие best practices не исполняются, если они реально best. Ядром Linux, все-таки занимаются не идиоты, или нет?А можно где-то что-то по поводу програмерской документации почитать? Что там должно быть, чего там быть не должно, есть ли какой-то open-source проект с выложенной «правильной» документацией?
А когда они скажут, что таки идиоты, мы приведем в пример другой open source проект.:) И будем так продолжать до победного конца.:)
знать хоть немного win32 api + ATL
А можно где-то что-то по поводу програмерской документации почитать? Что там должно быть, чего там быть не должно, есть ли какой-то open-source проект с выложенной «правильной» документацией?
Думаю, что противники документации — это те, кому лень ее писать. Придумываются всякие «read the source, luke» и т.п.
Руслан Шевченко 5 час. назадЮнит тесты, детальная проектная документация и митинги важны там где бюджет вообще не ограничен. Все это сделано более для того, чтобы контролировать индусов.
Господа, можно провести небольшой опрос, по поволду вброса gaperton: gaperton.livejournal.com/32772.htmlКак у вас в проектах обстоят дела с проектной документацией?
Лично я пишу документацию сразу в коде, пока никто не жаловался.
2 Всеволод Дёмкин
Тол попал в автокатастрофу
Сначала хотел написать именно так.Таки было предчувствие...
начать читать код;) по этому поводу в статье есть «правильная» картинка...
Я одного не понял: код был с вменяемыми коментариями или без? Потому что отсутствие документации это дело десятое, а вот функция-простыня на 3 экрана без единого комента это уже капец.Отличить геттер от сеттера все мы мастера. Адаптер от мессенджера тоже несложно. А вот почему применено именно это решение, как отличить код «избавляемся от поддержки устаревшего», от кода «закладываемся под будущее расширение»?
Собсно говоря — инженер перед производством рисует чертеж, офицер перед боем карту, хирург перед операцией ее план. Чем программисты лучше?
Підозрюю, що просто-напросто справа в тому, що ті, хто працював над цим проектом до Вас, всього-навсього не мали попереднього досвіду роботи над проектами такого масштабу (який би він там не був), ну от в них і вийшло, як вийшло. Я не прихильник теорій заговору.
До коментування коду є різні піхдоди. Я дотримуюся такого, що коментувати треба тільки ті місця, де код або 1) недороблений або 2) використаний який-небудь «хак». Варіант 1 досить швидко «виноситься», к-ть варіантів 2 можна перерахувати на пальцях однієї руки, як правило, це обхід яких-небудь системних багів. І працювати над, і повертатися до старих таких проектів не складає жодної проблеми. Але, звичайно, YMMV.
Вопросы в принципе можно задавать, но в данной ситуации вряд ли получу на них нормальные ответы. Вобщем думаю хватит обсасывать конкретно взятую ситуацию. Просто мое личное мнение, что документация должна существовать всегда.
2 greench
Ага наверно, систему 7 лет писали и она все-равно не доработана? За что вашей компании деньги платят?так проект не завершен и постоянно развивается,
Все-таки я бы не стал считать ваших предшественников «глупыми» или «неправильными», если они так делали, значит у них наверняка были какие-то основания так поступать. В любом случае, я думаю с ними можно будет как-то связаться (телефон, аська, скайп и тд) и задать им какие-то вопросы, лично меня это пару раз спасало.
2 kurtis: хе, так проект не завершен и постоянно развивается, так что лезть туда все равно прийдется. Как я уже писал это система, которая охватывает бизнесс процесс одного очень крупного предприятия и не бывает таких систем без глюков и доработок.
2 anonymous: Если вопрос ко мне, то отвечу. Код без комментов, тупо комментарии кто писал этот кусок кода и все.
Мне кажется что документация не велась т.к. «и так все понятно». И я практически уверен что через 3−4 месяца, лично Вам тоже влом будет вести документацию поскольку будет «и так все понятно»!greench2005
А вообще лучше не лезть чинить то что не сломалось. В свое время досталась мне в «наследство» мегабайт С89 исходников, причем некоторая часть была еще на ассемблере для intel 80c196. И ничего, со временем даже что-то умное делать научился=)) После определенного момента становиться понятно где можно что-то писать, а где этого делать ни в коем случае нельзя. Кстати комментарии встречались весьма редко, но всегда были в тему и помогали разобраться в написанном.
Другое дело, что это не делает ознакомление с ней легче для других. Впрочем, возможно для данного проекта такой цели и не ставится. Может, наоборот они не хотят, чтобы слишком много людей знали их тонкие ходы (типа, защита от пром. шпионажа):)
Я одного не понял: код был с вменяемыми коментариями или без? Потому что отсутствие документации это дело десятое, а вот функция-простыня на 3 экрана без единого комента это уже капец.
Гвоздь бы в голову вбить тому, кто принял решение не вести документации.
2 eugene_n: начать читать код;) по этому поводу в статье есть «правильная» картинка... Хотя согласен, что без документации и/или без людей, знающих предметную область и сам проект, понять что-либо сложно.
А с другой строны противоречит сам себе — какая может быть серьезная инженерия без документирования? Все хорошо, что хорошо кончается. А вот представить на секунду, что у Тола инсульт, автора перекупили конкуренты, а остальная команда от безнадеги разбежалась. Приходят новые люди, и с чего же им начинать?
Хорошая статья. И где-то я с автором согласен, что диаграммы быстро устаревают и код является лучшей документацией. Но непонятно как быть, если менеджеры (заказчики) люди далекие от программирования или если требования к отдельным частям системы меняются слишком часто и появляются спорные моменты — почему это работает именно так и не вот так... Мне спецификации писать приходится (хоть я и не в восторге от этого) перед разработкой чего-либо.
eugene_n
Сергей Дымченко
Олександр Краковецький
Alexander Belchenko
Alexandr Gavriluk
Михаил
Vsevolod Dyomkin
43 коментарі
Додати коментар Підписатись на коментаріВідписатись від коментарів