Проектная документация (опрос)
Господа, можно провести небольшой опрос, по поволду вброса gaperton: gaperton.livejournal.com/32772.html
Как у вас в проектах обстоят дела с проектной документацией?
Ruslan Shevchenko, Researcher
Facebook
Twitter
LinkedIn
eugene_n
Количество и качество документации в любом случае оплачивает заказчик. Он может не проконтролировать, тут уж на совести.
Мосье наверное не представляет, что бывают бизнесы, работающие на открытый рынок, без заказчика. И даже то, что таких бизнесов большинство.
Количество и качество документации в любом случае оплачивает заказчик. Он может не проконтролировать, тут уж на совести. Заказчику может быть пофиг документация — разовый проект, ПО через полгода снимут с эксплуатации. Вариантов много.
2 eugene_n. У мосье пиписька самая большая -это понятно, всё-таки «mission critical». Сорри за оффтоп.
Вот еще по теме: оценки стоимости одной строчки кода: в NASA и в индустрии. Это $850/LOC и $5/LOC соответственно
Сергей Дымченко
eugene_n, один-в-один мои мысли по этой статье.
Аналогия с самолетом хорошая: -)
Знову за рибу гроші...Можно сокрушаться по поводу отсутствия мифической и всегда актуальной документации
Я вот так и представляю себе цех Боинга, где работяга вместо того, чтобы прочитать размер в чертежах лезет со штангениркулем в потроха уже собранного самолета:)
Я понимаю о чем вы — когда 15 лет бегаешь латаешь и подмазываешь один и тот же софт, через некоторое время знаешь его наизусть. Только извините мосье — то чем вы занимаетесь, не инженерия, а кустарничество. Собственно как и у всей банковско/бизнесовой обслуги у вас крайне заужен кругозор, вы просто не представляете, что такое десятки клонов построенных на одной платформе, что такое жесткое соблюдение промышленных стандартов и наконец, что такое mission critical, где каждая бага может стоить жизни. Так что не обощайте пожалуйста и не обобщаемы будете.
> К примеру проект, которым я сейчас занимаюсь: > 15 лет разработки, писалось всеми подряд, в том числе индусами. > 300 метров исключительно исходников.
Пардон, виноват. 300 метров исходников — это не «достаточно маленький проект». Это, конечно, весьма большой проект. Я прочитал не «что написано», а «300 тыщ строк кода».
Пардон, виноват. 300 метров исходников — это не «достаточно маленький проект». Это, конечно, весьма большой проект. Я прочитал не «что написано», а «300 тыщ строк кода».
Тем не менее, суровая правда жизни в том, что чем больше проект, тем меньше вероятность, что вы найдете по нему вменяемую документацию.
> Read the code — ето конечно очень отличный совет, если проект небольшой, со свежей продуманной архитектурой, с вменяемыми кодерами, и наличием людей, стоящих у истков, или хотя бы очень глубоко разбирающихся в системе.
Проект, о котором идет речь в моей статье — на тот момент 10 лет разработки, и примерно 2.5 МИЛЛИОНА строк кода. Было в 2000 году. Сейчас сильно больше.
> К примеру проект, которым я сейчас занимаюсь: > 15 лет разработки, писалось всеми подряд, в том числе индусами. > 300 метров исключительно исходников.
Это достаточно маленький проект.
> Людей, участвующих в разработке с самого начала — не более 2х. Документации, не то чтобы 0, но чень близко к этому. Человека, представляющего себе полностью всю картину просто нет! Исходній код приводит в ужас любого — декларации классов на несколько тысяч строк, тела методов на столько же и т.п...
> Я могу сказать одно — сейчас без документации ОЧЕНЬ хреново (мягко выражаясь)!
Можно сокрушаться по поводу отсутствия мифической и всегда актуальной документации, избавляющей от необходимости читать код, чтобы его понять. Это в чем-то очень удобно, ибо она существует по большей части только в сказках. А можно — принять данность, и учится читать код.
И главное, учится его писать так, чтобы он был понятен без мифической документации. Писать литературно. Давать человеческие имена идентификаторам, включая мозги. Оформлять комментарии в неочевидных ситуациях. Использовать doxygen или javadoc. И обязательно, обязательно писать человеческие комментарии к коммитам. Вы не представляете, как это бесит, когда видишь в коде какой-то бред и вместо объяснения причины его происхождения в комменте к коммиту видишь фигу.
Проект, о котором идет речь в моей статье — на тот момент 10 лет разработки, и примерно 2.5 МИЛЛИОНА строк кода. Было в 2000 году. Сейчас сильно больше.
> К примеру проект, которым я сейчас занимаюсь: > 15 лет разработки, писалось всеми подряд, в том числе индусами. > 300 метров исключительно исходников.
Это достаточно маленький проект.
> Людей, участвующих в разработке с самого начала — не более 2х. Документации, не то чтобы 0, но чень близко к этому. Человека, представляющего себе полностью всю картину просто нет! Исходній код приводит в ужас любого — декларации классов на несколько тысяч строк, тела методов на столько же и т.п...
> Я могу сказать одно — сейчас без документации ОЧЕНЬ хреново (мягко выражаясь)!
Можно сокрушаться по поводу отсутствия мифической и всегда актуальной документации, избавляющей от необходимости читать код, чтобы его понять. Это в чем-то очень удобно, ибо она существует по большей части только в сказках. А можно — принять данность, и учится читать код.
И главное, учится его писать так, чтобы он был понятен без мифической документации. Писать литературно. Давать человеческие имена идентификаторам, включая мозги. Оформлять комментарии в неочевидных ситуациях. Использовать doxygen или javadoc. И обязательно, обязательно писать человеческие комментарии к коммитам. Вы не представляете, как это бесит, когда видишь в коде какой-то бред и вместо объяснения причины его происхождения в комменте к коммиту видишь фигу.
Все равно вы понятия не имеете как писать эту “документацию”, о которой вы говорите, и поддерживать ее в актуальном виде. Зачем же ожидать этого от ваших предшественников. Странно право. Делайте лучше нормально то, что вы можете и _должны_ уметь делать.
Опишу ситуацію документування, вірніше ситуацію взагалі з точки зору працівника ІТ (програміста) великого підприємства (просто описати: як у нас так з документуванням, картину).
1. Задач десятки (з закритими «по устарєванію» — більш сотні, хоча ті теж всплывають часом).
2. Кадри постійні. За останні 2 роки звільнилася 1 людина. Усіх менше 15 програмістів, які в тому ж числі аналітики, дизайнери, кодери, тестери, тех.письменники, впроваджувальники ну і т.п., «в міру способностєй».
3. Кожен веде свій напрям задач (ну, модним терміном — «у кожного свої проекти»), вірніше, група веде (2−4 чол.), але часом одна людина. Предметні області дуже різні, тому розподіл не технологічний, а предметний. Код кожного програміста як мінімум одна людина приблизно знає (у відпустку часом треба ж). Дуже правильна фраза з статті: «... — зачем на них смотреть, если они давно уже в голове? »
4. Модернізувати (крім виловлювання глюків, це теж) приходиться мало не щодня, причому «надо уже вчера! », без документів, навіть без ТЗ, усно: «хочу оте кенгуру щоб стало червоне і щоб плавало під водою». І розробка нових проектів паралельно (тут стараємся хоча б ТЗ написати, самі). І обробка-формування даних паралельно (вища інстанція ще більш дубова в плані аналітики — не знають, що їм потрібно для ефективного управління). І багато чого ще паралельно.
5. Якість ПЗ звичайно не MS (ORACLE, open source, IBM, підкреслити або вписати), але свої функції виконує.
6. Повне документування (працюємо згідно 34, 19, 24 ГОСТів) збільшує трудовитрати приблизно в 5 разів (правильно було сказано). «Високому керівництву», так як і користувачам, — документація не потрібна, їм робоча система треба. Юзери «Керівництво користувача» починають читати десь на 2-му-4-му місяці експлуатації, і то якщо задача має складну логіку (не програміст винен, закладено згідно «руководящих документів»). Так само як ОПЗ (опис постановки задачі) — жоден програміст не повертався до нього після початку експлуатації задач ні разу на моїй пам’яті (15 років). Воно потрібне — для того, щоб програміст краще розібрався сам в задачі, поки напише, і все. «Програму, методику испытаний», з прогонкою тестів, вимагаємо від сторонніх розробників, дуже сирі продукти часом (в основному на перших порах співробітництва, потім втягуються) приходять.
7. Документування застаріває раніше, ніж в задачі виловлять всі глюки (з багами не випускаємо). Рік назад здававли підсистему — половину документації вже треба переписувати. А тим часом користувачі навіть не помітили переходу на неї і всіх змін після, хіба що трохи вікна помінялись. Все собі працює.
8. Знову-таки, на моїй пам’яті найбільш успішні проекти пройшли або без документування, або воно йшло «заднім числом», «для галочки». І саме вони були впроваджені в найкоротші терміни і мали максимальну ефективність.
9. Інша команда не прийде на розвиток цієї системи, ніколи. Інша команда може впроваджувати щось типу SAP, тоді все рівно частина старої команди буде доробляти, специфіка залишається.
10. Тому документування йде «по можливості»: є час — робимо. Звичайно, коментарі в коді, коментарі до всіх об’єктів БД, всіх стовпців. Майже завжди — ЕРдіаграми. І осмислені назви всього (в більшості системно).
1. Задач десятки (з закритими «по устарєванію» — більш сотні, хоча ті теж всплывають часом).
2. Кадри постійні. За останні 2 роки звільнилася 1 людина. Усіх менше 15 програмістів, які в тому ж числі аналітики, дизайнери, кодери, тестери, тех.письменники, впроваджувальники ну і т.п., «в міру способностєй».
3. Кожен веде свій напрям задач (ну, модним терміном — «у кожного свої проекти»), вірніше, група веде (2−4 чол.), але часом одна людина. Предметні області дуже різні, тому розподіл не технологічний, а предметний. Код кожного програміста як мінімум одна людина приблизно знає (у відпустку часом треба ж). Дуже правильна фраза з статті: «... — зачем на них смотреть, если они давно уже в голове? »
4. Модернізувати (крім виловлювання глюків, це теж) приходиться мало не щодня, причому «надо уже вчера! », без документів, навіть без ТЗ, усно: «хочу оте кенгуру щоб стало червоне і щоб плавало під водою». І розробка нових проектів паралельно (тут стараємся хоча б ТЗ написати, самі). І обробка-формування даних паралельно (вища інстанція ще більш дубова в плані аналітики — не знають, що їм потрібно для ефективного управління). І багато чого ще паралельно.
5. Якість ПЗ звичайно не MS (ORACLE, open source, IBM, підкреслити або вписати), але свої функції виконує.
6. Повне документування (працюємо згідно 34, 19, 24 ГОСТів) збільшує трудовитрати приблизно в 5 разів (правильно було сказано). «Високому керівництву», так як і користувачам, — документація не потрібна, їм робоча система треба. Юзери «Керівництво користувача» починають читати десь на 2-му-4-му місяці експлуатації, і то якщо задача має складну логіку (не програміст винен, закладено згідно «руководящих документів»). Так само як ОПЗ (опис постановки задачі) — жоден програміст не повертався до нього після початку експлуатації задач ні разу на моїй пам’яті (15 років). Воно потрібне — для того, щоб програміст краще розібрався сам в задачі, поки напише, і все. «Програму, методику испытаний», з прогонкою тестів, вимагаємо від сторонніх розробників, дуже сирі продукти часом (в основному на перших порах співробітництва, потім втягуються) приходять.
7. Документування застаріває раніше, ніж в задачі виловлять всі глюки (з багами не випускаємо). Рік назад здававли підсистему — половину документації вже треба переписувати. А тим часом користувачі навіть не помітили переходу на неї і всіх змін після, хіба що трохи вікна помінялись. Все собі працює.
8. Знову-таки, на моїй пам’яті найбільш успішні проекти пройшли або без документування, або воно йшло «заднім числом», «для галочки». І саме вони були впроваджені в найкоротші терміни і мали максимальну ефективність.
9. Інша команда не прийде на розвиток цієї системи, ніколи. Інша команда може впроваджувати щось типу SAP, тоді все рівно частина старої команди буде доробляти, специфіка залишається.
10. Тому документування йде «по можливості»: є час — робимо. Звичайно, коментарі в коді, коментарі до всіх об’єктів БД, всіх стовпців. Майже завжди — ЕРдіаграми. І осмислені назви всього (в більшості системно).
Ну, трохи довго-нудно, але десь так приблизно.
Олександр Краковецький
Всего должно быть в меру — и документации тоже.
Я вообще писал в рассказе про вполне конкретную разработку
Было бы неплохо явно указать это. Потому что на волне этой публикации поднялась целая волна кричащих — долой документацию! Real programmers don’t have time to doc code! etc.
Read the code — ето конечно очень отличный совет, если проект небольшой, со свежей продуманной архитектурой, с вменяемыми кодерами, и наличием людей, стоящих у истков, или хотя бы очень глубоко разбирающихся в системе.
К примеру проект, которым я сейчас занимаюсь: > 15 лет разработки, писалось всеми подряд, в том числе индусами. > 300 метров исключительно исходников. Людей, участвующих в разработке с самого начала — не более 2х. Документации, не то чтобы 0, но чень близко к этому. Человека, представляющего себе полностью всю картину просто нет! Исходній код приводит в ужас любого — декларации классов на несколько тысяч строк, тела методов на столько же и т.п...
К примеру проект, которым я сейчас занимаюсь: > 15 лет разработки, писалось всеми подряд, в том числе индусами. > 300 метров исключительно исходников. Людей, участвующих в разработке с самого начала — не более 2х. Документации, не то чтобы 0, но чень близко к этому. Человека, представляющего себе полностью всю картину просто нет! Исходній код приводит в ужас любого — декларации классов на несколько тысяч строк, тела методов на столько же и т.п...
Я могу сказать одно — сейчас без документации ОЧЕНЬ хреново (мягко выражаясь)!
Alexander Belchenko
gaperton пишет: «В моем рассказе речь шла не обо всей-превсей документации, а об актуальной „внутренней“ документации по коду:).»
Знаете, в вашем рассказе это не очень конкретно написано. «Документация по коду».
Ну вот и разобрались что к чему.Я вообще писал в рассказе про вполне конкретную разработку, с конкретными признаками.
А за статью спасибо, хоорошо написана.
Кто бы спорил? Только не надо экстраполировать это на любую разработку.
Так и не экстраполируйте это на любую разработку. Кто заставляет-то? Я вообще писал в рассказе про вполне конкретную разработку, с конкретными признаками. Размер — большой. Возраст — большой. Людей — десятки, но меньше сотни. Развивается одновременно с поддержкой.
Кто бы спорил? Только не надо экстраполировать это на любую разработку.А вот в случае с внутренним продуктом, когда количество пользователей фреймворка составляет десятки человек, и они меняются редко — семинарские занятия будут эффективнее
2 rssh +1
> Только Вам это кажеться отсуствием документации, а мне наличием:)
В моем рассказе речь шла не обо всей-превсей документации, а об актуальной «внутренней» документации по коду:).
Внимательный читатель заметит, что лекции по архитектуре и CDP я к моменту диалога в рассказе уже прослушал, законспектировал, и усвоил.
В моем рассказе речь шла не обо всей-превсей документации, а об актуальной «внутренней» документации по коду:).
Внимательный читатель заметит, что лекции по архитектуре и CDP я к моменту диалога в рассказе уже прослушал, законспектировал, и усвоил.
К тому же, честно говоря я не вижу принципиальных преимуществ в передаче знаний Design Principles в виде документа, перед передачей этих же знаний в виде лекции-семинара. Скажем так, в случае с ядром Linux — понятно что эти преимущества есть. А вот в случае с внутренним продуктом, когда количество пользователей фреймворка составляет десятки человек, и они меняются редко — семинарские занятия будут эффективнее, хотя бы из-за наличия обратной связи при обучении. Очная форма обучения лучше и качественнее, чем заочная, с этим, я думаю, многие согласятся. Хотя, документировать Design Principles как минимум не вредно, и скорее полезно, даже в этих случаях, что тут говорить.
А, ну так в таком случае я с Вами полностью согласен: нужны именно Common Design Principles.
Только Вам это кажеться отсуствием документации, а мне наличием:)
> Хорошая документация увеличивает цену проекта в 5 раз (вот вам и все «лучшие практики», дело в цене).
Дело в целесообразности, а не в цене. Если внутренняя документация увеличивает стоимость разработки в долговременной перспективе, а не уменьшает, непонятно, зачем она вообще нужна. И цифра «5», к тому же, взята определенно с потолка.
> Узнайте сколько MS тратит на поддержку MSDN в актуальном состоянии.
Дело в целесообразности, а не в цене. Если внутренняя документация увеличивает стоимость разработки в долговременной перспективе, а не уменьшает, непонятно, зачем она вообще нужна. И цифра «5», к тому же, взята определенно с потолка.
> Узнайте сколько MS тратит на поддержку MSDN в актуальном состоянии.
MSDN это не «внутренняя документация», а «внешняя». А речь о внутренней. С какой стати мне это узнавать? Мне это не интересно, хотите — узнавайте.
Ну неужели Вы думаете, что я стал бы писать свой текст, ничего предварительно не проверив.:) Зачем мне спрашивать у гугля. Я уже знаю, что документация по подсистеме MTD, куда должен быть встроен драйвер NAND-Flash, отсутствует как класс, и поэтому наши программисты разбирались в ней по коду. И я знаю, что отсутствует документация по CryptoAPI, который сейчас находится в активной разработке, и куда надо встраиваться для разработки драйвера криптоускорителя, также отсутствует. И я знаю, в каком состоянии документация, например, по подсистеме ядра LinuxDVB (только внешний интерфейс, и _крайне_ скупо и лаконично).
Также мне известно, сколько времени ушло у наших программистов разобраться по коду в MTD, CryptoAPI, и LinuxDVB. Представляете, оказывается ничего страшного для человека, умеющего читать код! CryptoAPI вообще был расщелкан в пару дней.
Также мне известно, сколько времени ушло у наших программистов разобраться по коду в MTD, CryptoAPI, и LinuxDVB. Представляете, оказывается ничего страшного для человека, умеющего читать код! CryptoAPI вообще был расщелкан в пару дней.
А то, что надо знать как устроены драйверы в Linux вообще, и как они программируются — конечно надо, только это знание само по себе никак не поможет дать ответы на вопросы, которые я привел. Это так называемые Common Design Pronciples для написания драйверов, помогающие его читать и писать, и ни в коей мере не являются «документацией по коду».
Как раз по API ядра Линукса документации есть довольно много:
www.tldp.org/...html/index.html
(это что, обоим спорящим было лень спросить у гугля?)
// ну и понятно что там она нужна, так как это public API, для сторонних разработчиков, которых много.
Alexandr Gavriluk
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 проект.:) И будем так продолжать до победного конца.:)
Посмотри вот этот тест www.gamedev.ru/...es/rsdn_que_anw
Если на все ответишь почти без подсказок, то можешь считать себя C++ Junior’ом:)
Но обычно на себеседованиях спрашивают ещё о технологиях,
например если ты идёшь на visual c++ пограммиста то нужно уметь работать с Visual Studio
Если на все ответишь почти без подсказок, то можешь считать себя C++ Junior’ом:)
Но обычно на себеседованиях спрашивают ещё о технологиях,
например если ты идёшь на visual c++ пограммиста то нужно уметь работать с Visual Studio
знать хоть немного win32 api + ATL
А можно где-то что-то по поводу програмерской документации почитать? Что там должно быть, чего там быть не должно, есть ли какой-то open-source проект с выложенной «правильной» документацией?
Михаил
Думаю, что противники документации — это те, кому лень ее писать. Придумываются всякие «read the source, luke» и т.п.
Руслан Шевченко 5 час. назадЮнит тесты, детальная проектная документация и митинги важны там где бюджет вообще не ограничен. Все это сделано более для того, чтобы контролировать индусов.
Господа, можно провести небольшой опрос, по поволду вброса gaperton: gaperton.livejournal.com/32772.htmlКак у вас в проектах обстоят дела с проектной документацией?
Некоторая документация конечно нужна, возможно в виде диаграмм Поверпоинта, только для того чтобы посторонний мог въехать в идею архитектуры системы. Но документировать по классам?...
Лично я пишу документацию сразу в коде, пока никто не жаловался.
2 Всеволод Дёмкин
Тол попал в автокатастрофу
Сначала хотел написать именно так.Таки было предчувствие...
начать читать код;) по этому поводу в статье есть «правильная» картинка...
Я одного не понял: код был с вменяемыми коментариями или без? Потому что отсутствие документации это дело десятое, а вот функция-простыня на 3 экрана без единого комента это уже капец.Отличить геттер от сеттера все мы мастера. Адаптер от мессенджера тоже несложно. А вот почему применено именно это решение, как отличить код «избавляемся от поддержки устаревшего», от кода «закладываемся под будущее расширение»?
Где-то год назад я попал в ситуацию — в код вбросили поддержку нового стандарта, о существовании которого я не знал, а наши «архитекторы» не сочли нужным внести это в документацию. Вот это господа была головоломка, я вам скажу. Решилось проблема за 2 часа, но после
Внятно написанная документация это прежде всего чек-лист для самого архитектора, что все предусловия выполнены, скользкие места учтены, отходные пути при изменении требований продуманы — можно начинать. Если работа уже в процессе — внятное документирование изменений заставляет еще раз подумать: «А так ли они необходимы? » и таким образом избавляет от скоропалительных решений.
Собсно говоря — инженер перед производством рисует чертеж, офицер перед боем карту, хирург перед операцией ее план. Чем программисты лучше?
> Документация скорее всего (а зная всю подноготную могу утверждать это с 99% уверенностью) не велась для того, чтобы люди, работавшие над проектом стали незаменимыми и могли диктовать работодателю свои условия.
Підозрюю, що просто-напросто справа в тому, що ті, хто працював над цим проектом до Вас, всього-навсього не мали попереднього досвіду роботи над проектами такого масштабу (який би він там не був), ну от в них і вийшло, як вийшло. Я не прихильник теорій заговору.
> greench
До коментування коду є різні піхдоди. Я дотримуюся такого, що коментувати треба тільки ті місця, де код або 1) недороблений або 2) використаний який-небудь «хак». Варіант 1 досить швидко «виноситься», к-ть варіантів 2 можна перерахувати на пальцях однієї руки, як правило, це обхід яких-небудь системних багів. І працювати над, і повертатися до старих таких проектів не складає жодної проблеми. Але, звичайно, YMMV.
2 kurtis: вы как бы совсем не в теме того что, кто и для кого в данном случае пишет. Могу вас заверить, что в данном случае это нормально. Точка, дальше не будем вдаваться в подробности, просто приймите к сведению, что в данном моменте все всех устраивает с обеих сторон.
Я не говорю о глупости. Документация скорее всего (а зная всю подноготную могу утверждать это с 99% уверенностью) не велась для того, чтобы люди, работавшие над проектом стали незаменимыми и могли диктовать работодателю свои условия. Основная отмазка отсутствия документации — «некогда было писать», основная отмазка отсутствия нормальных комментариев — «так там и так все понятно».
Я не говорю о глупости. Документация скорее всего (а зная всю подноготную могу утверждать это с 99% уверенностью) не велась для того, чтобы люди, работавшие над проектом стали незаменимыми и могли диктовать работодателю свои условия. Основная отмазка отсутствия документации — «некогда было писать», основная отмазка отсутствия нормальных комментариев — «так там и так все понятно».
Вопросы в принципе можно задавать, но в данной ситуации вряд ли получу на них нормальные ответы. Вобщем думаю хватит обсасывать конкретно взятую ситуацию. Просто мое личное мнение, что документация должна существовать всегда.
2 greench
Ага наверно, систему 7 лет писали и она все-равно не доработана? За что вашей компании деньги платят?так проект не завершен и постоянно развивается,
Наверняка есть какое-то ядро, которое доведено до желаемой кондиции и куда в самом начале лучше не лезть. Можно посмотреть статистику системы контроля версий, отследить какие части менялись часто, а какие вообще не трогали длительный период времени.
Все-таки я бы не стал считать ваших предшественников «глупыми» или «неправильными», если они так делали, значит у них наверняка были какие-то основания так поступать. В любом случае, я думаю с ними можно будет как-то связаться (телефон, аська, скайп и тд) и задать им какие-то вопросы, лично меня это пару раз спасало.
2 kurtis: хе, так проект не завершен и постоянно развивается, так что лезть туда все равно прийдется. Как я уже писал это система, которая охватывает бизнесс процесс одного очень крупного предприятия и не бывает таких систем без глюков и доработок.
2 anonymous: Если вопрос ко мне, то отвечу. Код без комментов, тупо комментарии кто писал этот кусок кода и все.
Мне кажется что документация не велась т.к. «и так все понятно». И я практически уверен что через 3−4 месяца, лично Вам тоже влом будет вести документацию поскольку будет «и так все понятно»!greench2005
А вообще лучше не лезть чинить то что не сломалось. В свое время досталась мне в «наследство» мегабайт С89 исходников, причем некоторая часть была еще на ассемблере для intel 80c196. И ничего, со временем даже что-то умное делать научился=)) После определенного момента становиться понятно где можно что-то писать, а где этого делать ни в коем случае нельзя. Кстати комментарии встречались весьма редко, но всегда были в тему и помогали разобраться в написанном.
Vsevolod Dyomkin
2 eugene_n:
Тол попал в автокатастрофу (gaperton.livejournal.com/32772.html thread=425476#t425476). Это к тому, что то, о чем так часто любят говорить иногда сбывается.
Но понятно, что там у них есть команда из не менее десятка человек, знакомых с архитектурой не намного хуже его.
Тол попал в автокатастрофу (gaperton.livejournal.com/32772.html thread=425476#t425476). Это к тому, что то, о чем так часто любят говорить иногда сбывается.
Но понятно, что там у них есть команда из не менее десятка человек, знакомых с архитектурой не намного хуже его.
Другое дело, что это не делает ознакомление с ней легче для других. Впрочем, возможно для данного проекта такой цели и не ставится. Может, наоборот они не хотят, чтобы слишком много людей знали их тонкие ходы (типа, защита от пром. шпионажа):)
Я одного не понял: код был с вменяемыми коментариями или без? Потому что отсутствие документации это дело десятое, а вот функция-простыня на 3 экрана без единого комента это уже капец.
2 eugene_n: +1000
Сейчас столкнулся с подхватыванием системы, за уходящей командой. Документации 0. Система разрабатывалась около 7 лет, охватывает очень сложный бизнесс процесс. Разбираться в тоннах кода можно просто мозгом удариться.
Сейчас столкнулся с подхватыванием системы, за уходящей командой. Документации 0. Система разрабатывалась около 7 лет, охватывает очень сложный бизнесс процесс. Разбираться в тоннах кода можно просто мозгом удариться.
Гвоздь бы в голову вбить тому, кто принял решение не вести документации.
2 eugene_n: начать читать код;) по этому поводу в статье есть «правильная» картинка... Хотя согласен, что без документации и/или без людей, знающих предметную область и сам проект, понять что-либо сложно.
Двойственное чувство вызывает статья. С одной стороны автор достаточно внятно объясняет, что программирование это все-таки инженерия, а не говноляпство. И что голова набитая под завязку знаниями, без _умения_решать_задачи_ не стоит ничего.
А с другой строны противоречит сам себе — какая может быть серьезная инженерия без документирования? Все хорошо, что хорошо кончается. А вот представить на секунду, что у Тола инсульт, автора перекупили конкуренты, а остальная команда от безнадеги разбежалась. Приходят новые люди, и с чего же им начинать?
Хорошая статья. И где-то я с автором согласен, что диаграммы быстро устаревают и код является лучшей документацией. Но непонятно как быть, если менеджеры (заказчики) люди далекие от программирования или если требования к отдельным частям системы меняются слишком часто и появляются спорные моменты — почему это работает именно так и не вот так... Мне спецификации писать приходится (хоть я и не в восторге от этого) перед разработкой чего-либо.
43 коментарі
Додати коментар Підписатись на коментаріВідписатись від коментарів