caxapa.ru :: Всем привет. Возникла необходимость документирования софта, сдаваемого разработчиком. Ну с исходниками всё ясно, а как поступать с вспомогательной инфой (алгоритмы, блок-схемы, etc.) не совсем ясно. Как у вас решается этот вопрос?

Shura (27.10.2008 15:12, просмотров: 41677)

Всем привет. Возникла необходимость документирования софта, сдаваемого разработчиком. Ну с исходниками всё ясно, а как поступать с вспомогательной инфой (алгоритмы, блок-схемы, etc.) не совсем ясно. Как у вас решается этот вопрос?

- Поразил факт: 7 программеров и все программят на ассемблере. Неужели это так необходимо? Dir(2013 знак., 30.10.2008 03:38)
  - Кто сказал, что все? Не все и не всегда, а там, где это необходимо. - Shura(30.10.2008 10:11)
- а контроль версий используете? - yes(29.10.2008 13:55)
  - Нет, вообще ничего не используем. Поэтому бардак полнейший, я вот и пытаюсь как-то упорядочить это всё - Shura(29.10.2008 13:57)
    - как жыж вы докатились до такой жизни-то? - bialix_(29.10.2008 14:20)
      - Исторически. Разработчиков было всего 2, причём невзаимозаменяемых, поэтому в каком бы то ни было упорядочивании не было никакого смысла. Теперь их 7, поэтому назрела необходимость принятия мер. - Shura(29.10.2008 14:33)
        
        Может просто уволить 5? ;-) - she(29.10.2008 14:56)
        
        Уволить как раз тех двоих бы не помешало, вот в чём засада основная :-) - Shura(29.10.2008 15:10)
        
        Для начала нужно назначить начальника из их числа, затем внедрить контроль версий типа svn. Для обучения пригласить спеца из "больших программистов" - в Минске хватает. При конфликтах - разгонять всех, и правых и виноватых. - Vladimir Ljaschko(29.10.2008 14:41)
        
        Начало положено, начальник из их числа это я. :-)))) - Shura(29.10.2008 14:45)
        
        по svn усть книжка svn-book фри. где пытаются объяснить не только как пользоваться, но и зачем. собственно "освоить" тулзы там вопроса нет. важно именно "social problem" - то есть в людях. контроль версий хоть и не снимает вопроса с документацией, но yes(36 знак., 29.10.2008 19:42)
        
        Насчет социал проблем. Сейчас борюсь за то чтобы каждый из коммитов соответствовал одному багу или одной фиче. А то есть любители коммитить один раз в месяц, обычно перед релизом. ;/ - diper(30.10.2008 13:00)
        
        хотел сказать что-то едкое, но воздержался. чаще надо этим заниматься, чаще! чтоб застоя крови в малом тазу не было! - bialix(30.10.2008 22:40)
        
        *сделал невинные глаза* Чем чаще заниматься? - diper(30.10.2008 22:52)
        
        Где она есть? ;-) - Shura(30.10.2008 10:12)
        
        блина, да в гугле =) - Alex B.(30.10.2008 10:20, ссылка)
        
        Ёпта, спасибо. Чтоб гуглить - название знать надобно :-) - Shura(30.10.2008 10:22)
        
        "svn book" - первая ссылка =) - Alex B.(30.10.2008 10:26)
        
        +1 - Alex B.(29.10.2008 23:14)
        
        :-) Не очень удачное решение, поскольку программирование - не самая сильная твоя сторона(насколько я понимаю). Можешь пойти на поводу. Вместо жесткой архитектуры программы получишь какую-то документацию, по которой точно также нельзя будет ничего понять. - Vladimir Ljaschko(29.10.2008 14:55)
        
        Я не только за программистов отвечаю, а за всех разработчиков в целом. Поэтому я не могу быть одинаково силен со всех сторон. :-) - Shura(29.10.2008 15:09)
        
        Это понятно, ты и так слишком хорош :) - Vladimir Ljaschko(29.10.2008 15:29)
- Шура, начните для начала с внедрения ревью кода. bialix_(1158 знак., 28.10.2008 14:11)
  - Имеет ли смысл делать ревью на начальных этапах, когда кода пишется много и большая часть из которого заглушки для будущей функциональности? Т.е. много "мусора", который ревьювить имеет смысл только на соответствие кодестайла. - diper(28.10.2008 14:36)
    - так не пишите заглушки, а пишите только по существу. на начальных этапах неплохо бы архитектуру проработать. код -- это отражение архитектуры. если код пишется из головы, без оглядки на какой-то архитектурный план, то ревью как раз выявит дырки в bialix_(24 знак., 29.10.2008 13:29)
  - Такая мысля тоже была, спасибо. Только это, имхо, не в начале а в самом конце ужо должно быть Shura(127 знак., 28.10.2008 14:17)
    - это идеальный порядок вещей. у вас проблема (как я понял) с формализацией п.1 и 2. Потому и предлагаю начать с п.3. чтобы четче стало понятней чего не хватает. - bialix_(29.10.2008 13:32)
    - Trac is an enhanced wiki and issue tracking system for software development projects - diper(28.10.2008 14:32, ссылка)
- В конструкторская документация должна обеспечивать производство информацией, ++(128 знак., 28.10.2008 10:06)
  - А алгоритмы- это более ранняя стадия проектирования (напр эскизный проект ....) Если Вы делали сразу рабочий проект ++(51 знак., 28.10.2008 10:11, ссылка)
- Эти все алгоритмы обычно исходникам не соответствуют. Шоб были на всяк случай можно включить файлы в проект исходников, а уделять им время не стоит. - Vladimir Ljaschko(27.10.2008 16:03)
  - Вот мне именно надо, чтоб соответствовали. И время уделять придётся. Вопрос как раз в оптимизации этого времени - чтоб не слишком много уходило, но при этом оставался достаточный уровень документированности. - Shura(27.10.2008 16:21)
    - Это утопия =) - she(27.10.2008 16:47)
      - Ответ: - ++(28.10.2008 10:14, ссылка)
      - По делу есть чо сказать? Не верю, что никто нигде этого не делает. Раньше даже ГОСТы были. - Shura(27.10.2008 16:55)
        
        Ну разрисовывал я всякие диаграммы состояний, последовательности обмена в UML'е для зоказчегов. Ничо так, даже полезно на этапе продумывания архитектуры софта. Но времени жрет уйму, и если этим заниматься на протяжении всего прожекта, свихнуться можно. she(385 знак., 27.10.2008 17:26)
        
        А можно вот пример глянуть как это выглядит? - Shura(27.10.2008 17:32)
        
        Пример с ibm.com устроит? she(302 знак., 27.10.2008 17:44, картинка)
        
        Как-то неинформативно совсем. А по "формальным требованиям" можно подробнее? У нас вопрос стандартизации сотфа в зачаточном состоянии вообще, "каждый др.чит, как он хочет" - Shura(27.10.2008 17:46)
        
        По формальным - разумный минимум, все вроде и так знают: she(451 знак., 27.10.2008 18:12)
        
        Я бы за ассемблер сразу давал в глаз, потому что меня клинит от одной команды jmp :-) - Vladimir Ljaschko(27.10.2008 18:24)
        
        А по с++усалам? :)) - MBedder(27.10.2008 19:05)
        
        Прости! ...но все равно клинит :) - Vladimir Ljaschko(27.10.2008 19:22)
        
        у меня, конечно, не по стандарту, но как-то так Alex B.(67 знак., 27.10.2008 17:50)
        
        Ну и у меня не по стандарту. И только интерфейсные вещи. Vladimir Ljaschko(27.10.2008 18:07)
        
        Это уже понятнее намного :-) О каком стандарте идёт речь? - Shura(27.10.2008 17:54)
        
        У меня-то "ниокаком" =) У she - об UML - Alex B.(27.10.2008 17:59, ссылка)
        
        Шура, я лично по ГОСТам делал 20 лет назад! Никому не нужная работа. Если программер твой - зачуханный ассемблерщик, то фиг тебе алгоритмы помогут. Человеческий фактор на первом месте. Разобраться не может... - Vladimir Ljaschko(27.10.2008 16:58)
        
        Алгоритмы это первооснова. Саму прогу я могу дать другому челу переписать, но нужно знать, как она работает - Shura(27.10.2008 17:00)
        
        Спорить не буду, сейчас скажешь что "сложная обработка датчиков", бла-бла-бла... Но мы то понимаем, что причина проблемы - непрофессионализм. - Vladimir Ljaschko(27.10.2008 17:04)
        
        Нет, там другая причина на самом деле, причём намного хуже. Но это к делу не относится. Насчёт датчиков - практически угадал :-) - Shura(27.10.2008 17:11)
    - А как ты это соответствие собираешься обеспечивать? Программиста на допрос и иголки под ногти? :) Для начала выбери подходящую среду для алгоритмов попроще. И установи правила синхронизации с версиями ПО. - Vladimir Ljaschko(27.10.2008 16:31)
      - Паяльником обеспечивать буду :-) Что за среды для алгоритмов? Я не в теме совсем - Shura(27.10.2008 16:36)
        
        Ну в чем ромбики рисовать будешь? В Visio, как все студенты, в Chartist, как маразматичные профи, или в чем-то современном? Кстати, заказчиком эти программы должны быть куплены. Может, таки нафиг? :) - Vladimir Ljaschko(27.10.2008 16:46)
        
        Да мне похер ромбики, можно и в текстовом виде описывать. Суть не в этом, а в том, чтобы хоть как-то описать структуру и алгоритм работы программы. - Shura(27.10.2008 16:54)
        
        ой, да ладно вам. Софтин для рисования ромбиков бесплатных хоть ( | ) ешь. Навскидку - Dia, yEd, ну и еще какие-то смотрел. Вопрос-то не в этом... - Alex B.(27.10.2008 16:53)
        
        Сейчас - да. Просто я сталкивался с комбинацией алгоритмы+заказчик. Простейшие вопросы не решаются. - Vladimir Ljaschko(27.10.2008 17:08)
        
        Здесь проще, заказчика нет как такового, докУмент нужен для внутреннего пользования - Shura(27.10.2008 17:12)
        
        если стоит выбор рисовалки - то могу посоветовать yEd. Alex B.(61 знак., 27.10.2008 17:28, ссылка)
        
        Пока вопрос более общий - что, как и в каком объёме требовать с разработчика - Shura(27.10.2008 17:29)
    - что понимается под достаточным уровнем? Кому-то достаточно doxygen + graphviz. Если для ваших диаграмм (не зависимостей, которые doxygen стоит сам по исходникам) будет достаточно средств graphviz, то это, имхо, лучший вариант. Прям в комментарии Alex B.(182 знак., 27.10.2008 16:30)
      - еще как вариант - Understand for C/C++ - но это все таки больше для анализа, нежели для документирования. - Alex B.(27.10.2008 16:32, ссылка)
        
        Не подходит, софт на ассемблере в основном - Shura(27.10.2008 16:34)
        
        Если для продукции Atmel, то Algorithm Builder :) бомж(27.10.2008 22:55)
        
        хм. А что тогда значит "с исходниками все ясно"? Я думал doxygen и юзаете, раз все ясно... - Alex B.(27.10.2008 16:37)
        
        Значит, что исходники просто сдаются в архив. Разобраться с ними никто, кроме аффтара не может, да и сам аффтар по истечении времени в них разобраться не может. Отседова и вопрос возник - Shura(27.10.2008 16:41)
        
        ну тады ой. Если бы на С/С++ - то юзать доксиген и не парится. Все равно, конечно, осталась бы проблема лени и похуизма, но как я понял, за аксиому берем что все молодцы. Но все равно согласен с she, в идеальный порядок все привести не удастся =) - Alex B.(27.10.2008 16:55)
        
        Doxygen и другие ф топку. Сильно зесераются исходники. У нас от него остались только шапочки для файлов и функций. diper(255 знак., 27.10.2008 17:47)
        
        да-да, я тоже так думал. Вы путаете комментирование и документирование. Если у вас документация никак не связана с исходниками, то держать ее в актуальном состоянии это ацкий труд, проще будет совсем на это болт забить. Alex B.(543 знак., 27.10.2008 17:58)
        
        ... если модуль сложный, то описание его работы расписано в шапке. Тоже касается функции. Размеры не смущают. Держится в более менее актуальном состоянии. Прелипил шапку одного модуля, текст не важен, главное количество :) diper(27.10.2008 18:10)
        
        есчо раз - вы говорите про комментирование исходников. Я про документирование - т.е. про отдельный от исходников документ, который им [теоретически] соответствует. Alex B.(588 знак., 27.10.2008 18:19)
        
        Усе понял. У нас как то не сложилось написание отдельных документов. Обычно на проект (если это одна функционально законченная железка) разработчик для себя составляет один документ в котором расписаны неокторые ньюансы, которые в исходник запихать diper(381 знак., 27.10.2008 18:31)
        
        во-во. "Когда уходит разработчик" - это один из вариантов, когда нужна документация... - Alex B.(27.10.2008 18:37)
        
        Дык вот и вопрос - какая документация? - Shura(28.10.2008 10:52)
        
        Да никакая ;) AlexandrY(325 знак., 28.10.2008 20:43)
        
        БДСМом увлекаетесь? :) - diper(28.10.2008 21:53)
        
        С чего-то надо начать хотя-бы, к идеалу будем приближаться итерациями :-) - Shura(27.10.2008 16:57)

Микроконтроллеры