Колеги,
Искам да повдигна тази тема, защото от много време се чудя и се опитвам някак си да "вкарам в ред" софтуерната част и документацията и на проектите по които работя.
Предполагам, че всеки един от вас неведнъж си е задавал или ще си зададе подобен въпрос.
Преди време във форума в мои "постове" частично засегнах темата с ефективността при разработването и поддръжката на проекти, но мисля, че определено си струва заедно да помислим и обменим опит и идеи по темата.

Та за какво иде реч:
Всички сме чували и сме се смяли на законите за конструктурската документация, а именно:
1. Ако трябва да съществува - не съществува
2. Ако съществува - значи е остаряла
3. Само безполезната документация успява да прескочи първите два закона

Та въпроса е как да се организира и води работата по един проект така, че горните три закона да не са в сила.

Има разни програмни пакети като Raphsody и Rational Rose, които са създадени малко или много да решат тези проблеми, но така и не успявам да намеря начин и технология на работа, която да ги направи малко или много приложими за моята работа.
Има и програми като Development Assisten for C на Ristan Case, която генерира автоматично документация на проекта, но някак си това като че ли е недостатъчно и е използваемо едва след като проекта е реализиран.

Разбира се програмите за VersionControl като CVS, PVCS и др. са много полезен и бих казал задължителен инструмент който трябва да използваме, но те имат отношение по-скоро към версиите, архивирането и history-то на проекта.

IAR предлагат "Visual State" - система за автоматично генериране на код, но подхода им беше изцяло реализиран върху стейт-машина, а това не винаги е подходящо и удобно.

Идеята е архитектурното проектиране, имплементирането и документирането да вървят ръка за ръка и винаги да са "Up to date" - така че работата на хората в екипа работещ по проекта и поддръжката му максимално да се улесни и онагледи.

(В случая нека не разглеждаме чисто мениджърски програми като Microsoft Project)

Нека се фокусираме върху проекти за ембедед системи писани на C (а не на C++ и др. обектно ориентирани езици от високо ниво). Т.е. на проекти и системи реализирани с едночипови микроконтролери.

Някой от вас има ли опит и идея как да се организира работата по проекта в такъв аспект - или пък опит с такива или подобни системи?

С всичко съм съгласен, но не и с това...

Значи да уточня, че говорим за чисто конструкторска документация, а не за "ръководство на лузера"... Та тая документация е необходима поради две причини:
1) Късата памет на конструктора. Аз лично помня колкото маймуните и честно казано не се старая да помня всичко, щото то една (две) глави не стигат.... Затова гледам да не забърквам каши и да си оставям поне малко документация, че след време ако (като) се наложи да преправям да мога да се ориентирам по-бързо.
2) Работа в екип, т.е. по всяко време да могат нови хора да навлизат в проекта, както и да работят паралелно без да се налага постоянно да обсъждат кой какво прави и как го прави.

Според мен това са основните причини за документация. Ех, разбира се, понякога когато клиентът плаща за сорсовете или проектът е за SDK, т.е. документацията е важна част от крайния продукт, но тези случаи са изключение и не ги коментирам. Говорим за общия сличай, когато документацията е тъй да се каже за "лични нужди".

Та при тия уточнения, мога да кажа че нищо не е толкова ефективно, колкото средствата за versoin control. Особено ако говорим за "работата в екип" и то екип, който физически не е в един офис. А дори и на едно бюро да работят, тия средства пак са незаменими. Просто една синхронизация е достатъчна за да видиш кой какво и къде е пипал. Няма нужда да се обеснява надълго и нашироко, да се менкат файлове, отпадат всички рискове да се загуби нещо от някого.

С две думи, cvs и подобните средства действително решават проблемите, за разлика от "докуметацията", която има уж същата цел, обаче на практика не върши никаква работа. Емо много добре е написал, че тя или отсъства, или ако я има, изобщо не е актуална...

Разбира се, тия средства не отменя нуждата от някакво "документиране". В случая аз съм консервативен и предпочитам да слагам коментари из сорсовете. Още повече, че съвременните IDE-та са толкова мощни, че е достатъчно човек да спазва елементарни правила при писане и от там нататък не е нужна детайлна документация. Примерно в Eclipse само посочваш с мишката някаква функция и може да видиш и дефиниция и сорс и всичко. Иначе всички IDE-та си имат мощни търсачки, така че за секунди може да намериш и самата функция и къде и как се ползва. Та за тия неща дори и да има документация, аз лично не бих я използвал.
Слагам коментари предимно за по-завъртяни алгоритми и обработки, така че човек да може да се ориентира какво прави сорса. И тук срествата за version control са много полезни, защото с времето алгоритмите се налага да се променят и старите коментари почват да пречат. От друга страна като тръгнеш да сменяш нещо концептуално, понякога работата не става и се налага да връщаш стари алгоритми. Без cvs се получава боза, защото не е добре да махнеш стария сорс и коментари докато не тръгне новия, а като тръгне пък повече нищо не пипаш и така се трупат глупости. Докато при наличие на cvs, притесненията че ще се наложи да върнеш нещо са излишни, затова спокойно трия всичко старо. Оставям само актуални неща и коментари - това дори е задължително, защото после е много по-лесно сравнението. И ако нещо се не тръгне виждаш какво си махнал, какво си добавил и т.н.

Та така... ползата от cvs, svn и прочие е предимно при организацията и при самото бачкане. Това че може да се ползват и за "архивиране" е просто фючър без голямо практическо значение...

конструкторска документация и софтуер? че от кога сковаването на джамове стана инжинерна наука

ако е основно за софтуер - хвърли един поглед на doxygen-а http://www.stack.nl/~dimitri/doxygen/
с малко допълнителна дисциплина при писане се получава изключително добра документация на html и pdf.
в комбинация с CVS/SVN се обхващат и версиите.
за поддръжка си има също подходящи системи (TRAC примерно)

за механична/електрическа документация май си е най-добре хартията.
но там си има много стари правила (ЕСКД) и човек бързо се научава за ползата от тази бумажтина.
не съм виждал някакво средство за автоматизиране на процеса.
едно вътрешно вики може да помогне да се водят бележки и документация по проекта

Основното средство, което човек ползва за документиране на работата си, е на
2-3 хиляди години - латинската азбука.

От известно време имаме и директории, поддиректории и т.н.; че даже и картинки
(снимки на прототипната платка, та да се виждат поправките са безценни).

Не съм ползвал т. нар. "verson control" и подобни глупости; и не планирам да почвам.
Организирам си нещата така, че да мога да се ориентирам и после в тях.

Подходящи имена, подходящи съкращения.
Разумно разделяне на нещата по файлове. Все такива очевидни неща .

***___ КОМЕНТАРИ___*** - достатъчно, за да може човек да разбере какво прави
и как работи даден софтуер дори без да знае езика, на който е програмирано.

Не особено отдавна ми се наложи да бъркам в софтуер, който съм писал преди над
20 години (емулирана стара система, чиято мишка беше прекалено хардуерна, та да
е лесна за емулиране, по-лесно беше да пипна в (пра)стария код).
Ми отне ми по-малко от час.

Хрумна ми още нещо в тая връзка.

Ползването на ненужни автоматизации на процеса е вредно.
Вършенето на някои рутинни неща, които автоматизацията не би ускорила
(писане на скриптове за това-онова, търсене на нещо по дъмпове и т.н.) поддържат
формата. Знаем какво става ако човек си загуби формата дори да става дума за
мускули, по-елементарни от тоя в черепната кутия .

Ами лично за хардуера, включвайки, схеми, платки, механични елементи, снимки и вс. останало го държа в директорията на проекта, където има версии има отделни поддиректории или файлове, зависи колко обемист е проекта. В тази директория стоят и заданията, и всички документи генерирани по врме на развоя. Относно софтуера, фърмуера обикновенно ми седи в същата директория, относно софтуера аз не пиша такъв, ил по скоро само елементарен такъв, но това което някой ми пише също се организира по подобен начин. Реално досега съм нямал голям софтуерен проект. В момента правим нещо мнооого голямо, и се ползва контрол на версиите а и автоматично генериране на документация.
И всички директории ми стоят в една директория изделия, която се бекъпва редовно и тва е .. нямам грижи, поглеждайки в тази директория виждам 161 в момента поддиректории, т.е. 161 изделия е някои са за версии ... всичко се намира лесно и бързо.

Колеги,
Въпросът ми беше как да се организира развойният процес така, че документацията да се получава по време на разработването.
Програмите като DAC на Ristan Case за която ви писах е подобна на тази която Дедо Боре казва, но те генерират документацията след като проекта е готов - на базата на коментарите в софтуера.

Въпросът ми е за програма или технология, която да се използва по време на проектирането (архитектурното декомпозиране на проекта на подзадачи или подпроекти), като по този начин хем да генерира документация, хем да онагледява и подпомага декомпозирането на проекта на подпроекти...

Да- можем примерно с Visio да си начертаем някакви стейт или UML диаграми, но обновяването им трябва да го правим ръчно при промяна в кода...

А това че "голямата автоматизация води до големи проблеми" - както казва tgi - спор мисля че няма

По скоро трябва да има нещо както в PCB програмите за разработване на печатни платки - като ECO (Engeneer Change Order). При промяна на стойността на компонент в схематика - автоматично се обновява и стойността му в платката. Или пък при промяна на корпуса на компонент в платката - автоматично се обновява атрибута на компонента в схемата ... Т.е. дизайнера не се занимава с рутинни и неприятни дейности, при които вероятността за грешка (човешки фактор) е голяма, а всичко става автоматично... Това си е ГОЛЯМА АВТОМАТИЗАЦИЯ, но не ми се вярва да не я ползвате ...

Иначе и аз работя по подобен начин на това, което описвате до момента, но някак си не ми изглежда много ефективно ... Може би това произтича от това, че работим в малки колективи или самосточтелно и някак си не ни се е налагало да мислим по-голбално ... Знам ли ... Но когато трябва да работят повече от 2-3 човека по един проект и то само по софтуера - въпросите несъмнено възникват ...

В проекта подреждам подпроектите в отделни директории, използвам PVCS, използвам понякога DAC-a, даже някъде съм чертал и на Visio, но някак си всичко това не ми изглежда много добре поради факта, че документацията не се обновява автоматично ...
Нещо повече - нещата значително се усложняват, когато примерно от няколко архива в PVCS използваме библиотечни или програмни кодове в повече от един проект - примерно драйвери, бутлоадери и т.н.

А от кода (или коментарите в кода ако ги има) не е добра идея да се сваля информация как работи даден софтуерен модул по време на запознаване с даден нов за нас проект ... Това си е малко или много "ревърс инженеринг" на който определено не съм фен ... А програмите които автоматично генерират доументация от кода - в повечето случаи не са много ефективни и полезни с информацията си, която генерират ...
Е, ровенето в кода е неизбежно, когато вече знаем как работи системата и когато искаме да променим нещо в нея, но тука ключовата фраза беше "знаем как работи системата" ... а документацията ни трябва за да разберем точно това, нали?

Примерно DAC-a може да направи блокова диаграма на код на "С" като даже от коментарните полета да "екстракне" текст и да го постави в самите блокчета на блоковата диаграма- и то така, че да четем само блоковата диаграма и да "разгадаем" функционалността. Може да направи и "Call-Graph" на функциите, както и описание на променливите, но това няма да може значително да ни улесни при "разгадаването" на някой нов за нас проект - разработен от други ... Нали "

Предполагам, че в големите развойни фирми се ползват програми и има технология на работа - решаваща гореописаните проблеми... Някой знае ли такива, или пък да рабити или да е работил с такива?

честно казано не разбирам какъв точно ти е проблемът... Засягаш няколко съвсем различни теми.

Проблемите и триковете при използване на PCVS са една тема.

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

Планирането и заданието е друга тема... Управлението на проектите е друга тема..

Универсалните инструменти дето готвят, перат и простират също са друга бира...

По-скоро бих казал "прекалената" вместо "голямата", нали тук всички
баш голямата автоматизация гоним като ефект . Но явно говорим за едно и също, де.

По-глобално - ами ти май искаш да направиш подобрен човешки мозък, дето освен
да знае повече от тебе да е и послушен. И аз искам, ама не знам как .... засега .

Но целта си струва - или поне така ни е конструктивно заложено да мислим - та и ти, и останалите
тук и другаде ще продължаваме да дерзаем.

Идеята ти да синхронизираш работата на два-трима души по даден софтуер не е особено
практична. Едва ли ще искаш да делиш софтуера на парчета за разни хора, ако ще се
пише за по-малко от 3-4 месеца; а ако има над 3 месеца работа по него, то не е особено голям
проблем да се раздели на доста независими една от друга части за разните хора.
Това последното го говоря наизуст, разбира се, аз програмирам сам.

е, има такива устройства. ама мноо мърморят, искат да ги водиш на кино, че и за ръка да ги държиш

аз ще си карам на doxygen, поне не спори за щяло и нещяло

Проблем за сега нямам, но искам да организирам нещата около мен така, че да намам и за в бъдеще. Та в тази връзка се опитвам да разбера, а и заедно да помислим над въпроса с разработването, поддръжката и документирането на един проект.

Миро - прав си, че PVCS-a няма общо с планирането и заданието, но и той е част от организацията на работата по даден проект. А именно в частта с версиите и поддръжката. Бъг-тракера - е създаден спецялно за поддръжката. Да кажем, че имам идея и опит с тази част от организирането на работата. (всъщност тези неща предполагам съвсем не са нови за тебе)

Но какво да кажем за проектирането и декомпозирането и документирането на проекта?
За момента нямам решение, което да ми се вижда свястно и работещо ...

Някой има ли опит с UML или др. такива? В смисъл да е започнат даден проект от "0" и изцяло да е разработен и документиран с подобни средства? Интересно ми е да разбера каква е технологията на работа ... (иначе и аз съм чел разни книжки за UML, но не съм виждал никъде "завършен такъв проект" и то за ембедед системи писани на "необектен" език за програмиране - примерно "С") Т.е. липсва ми пример показващ технологията на работа ...

Относно UML... и аз преди време се бях насочил [url = http://mcu-bg.com/mcu_site/viewtopic.php?p=49691 ] натам [/url], но не стигнах до практическо използване. Причините бяха две - първо, UML изисква известни познания, т.е. става за достатъчно голям проект при който можеш да си позволиш лукса да обучиш персонала. При нас по-скоро нямаше време, а и персонала не беше ясен, така че се отказах да правя нещо дето само аз ще го разбирам/ползвам. Другата причина е интеграцията със сорсовете. Значи без интеграция се губят много от предимствата на цялата работа. А пък интеграцията предполага обектно ориентирани езици като Java/C++ и е по-трудна за просто С или пък асемблер. Евентуално ако минем на С++ може пак да се побъзикам с UML...

Има и нещо друго, целият работен процес трябва да не е много сложен. С други думи никак не е разумно да ползваш 15 инструмента - един за планиране/моделиране, друг за писане/дебъгване на сорсове, трети за вершън контрол, четвърти за project/task managment, пети за документация и т.н. и т.н. Просто станат ли много инструментите кашата е гарантирана. Винаги се появява някой от екипа, който не владее или не желае да ползва даден инструмент и организацията се чупи.

Всъщност за този проблем има едно решение наречено Eclipse. Това е изключително мощна платформа, която позволява интегрирането на много инструменти в едно. Не само изброените, а много повече - аз примерно в сегашния проект освен фърмуер ми се наложи да правя и web сървър, т.е. xml, html, php, wml файлове. И всичко го бачкаме в Eclipse, при това без каквито и да е компромиси. И като среда за С-програмиране е перфектен и като среда за веб програмиране и като вершън контрол е много добре.

Но Eclipse е решение ако се ползва GCC... Ако проектът е базиран върху някакъв комерсиален компилатор/среда може да възникне лек конфликт

Miro, точно от това се интересувам за което пишеш. И аз преди време правих опити да разуча Raphsody, но общо взето стигнах до изводите които ти описваш и се отказах от това по същите причини.
Почти съм сигурен, че подходът ми към разучаването на тази система не беше от най-ефективните. За съжаление не намерих проект (даже и демо), който да описва цялостният процес на работа с програмата, та даже и такъв от който да се схване идеологията и най-важното - ТЕХНОЛОГИЯТА на работа при разработването и описанието на проекта. (говорим за "С" а не "С++" ембедед проект) Знаейки каква е крайната цел се опитвах да разбера и да създам технология на работа, но това не ме доведе до нещо работещо и смислено.
Т.е. имам нужда (а предполагам и повечето от вас които са решили да работят в тази посока) да обсъдя с някой, които има опит с подобни програми, за да разбера мнението му, а и технологията на работа. Т.е. да видя един реален проект изцяло разработван по тази технология ... Това е причината да постна тази тема във форума...

Давам си сметка, че в БГ едва ли има фирми (определено мисля, че трябва да са големи), които да използват тази технология в развоният си процес, но все пак определено си струваше да опитам да го обсъдя с вас ...

Знам, че във форума има и доста хора работещи извън БГ, които можеби имат или са имали възможността да работят по този начин, с които бихме могли да поговорим за това ... А може би трябва да ги потърсим в други форуми ... Някакви идеи по въпроса?

Разбирам, но не мога да помогна в тая насока...

Не съм срещал "цялостно" решение, а и не мисля че такова съществува. Проблемът е по-скоро в хората... Значи аз съм се пробвал да наложа частични решения, примерно за планиране на задачи и други подобни, но в крайна сметка не се получава поради една или друга причина...

Доколкото мога да предположа почваш нов и сложен проект и около теб е хаус. Познато ми е това усещане Надяваш се, че ако намериш "правилния" инструмент ще вкараш някакъв ред... Но обикновено "редът" идва от самосебе си с натрупването на опит. Ако мога да дам съвет, не търси генерални решения. Съсредоточи се в конкрените дребни инструменти и гледай да избуташ проекта.

Според мен от избора на "дребни" инструменти зависи много. И това ще е по-полезно за обсъждане тук, щото е и по-конкретно. Примерно като спомена PVCS го погледнах и не ми се стори добро решение... То зависи как и за какво го ползваш де. Ако ползваш и останалите инструменти на тая фирма може и да има някакви предимства. Ей такива конкретики можем да коментираме...

BTW аз в момента разполагам с някакво свободно време и едно от нещата дето евентуално мисля да направя е да си "преразгледам" инструментите... Но аз дълбая само в една посока - АРМ+GNU.... Ако има и други мераклии, можем да отворим специална тема, демек да коментираме всичко от игла до конец за развой на ARM - среди, OS, инструменти, стекове и прочие... Мисля че мога помогна с някои неща, за други аз не бих отказал съвети. Примерно решил съм твърдо да мина от С на С++...

Миро,
Работим с PVCS и съответно с бъг-тракера му. Държи се стабилно и намам забележки към него. Позволява импортване на файлове от един проект в друг (така сме организирали част от библиотеките). За сега нямаме изисквания, които той да не удовлетворява.

Като текстов редактор използвам CodeWrite. На времето използвах MultiEdit, но от както открих CodeWrite - се "родих".
Чувал съм за Еклипс-а, но на времето отзивите от колеги бяха, че е мнооого тромав за работа. Окупира почти цялото процесорно време. Какво е мнението Ви за него?

CodeWrite позволява интегриране на PWCS и "Development Asistent for C" в него. Позволява и прихващане на изхода на компилаторите и линкера (парсира ги), но това не го ползвам. Използвам го само като сорс код редактор. Дебъгването го правя в съответната среда в зависимост от процесорите с които работя - SofTune, Keil, IAR или MicroChip MPLAB.

За сега гореизброените IDE-та нямат свястни вградени текстови редактори в себе си и за това технологията на работа ми е такава.

За чистото прогнозиране, администратиране и организиране на работата по проектите - планираме с Microsoft Project.

Да - до момента и за в момента - SW проектиране го правим без спецялни инструменти като CASE и т.н., но всеки път при започването на нов проект (или подпроект) си мисля за недобрият начин на работа. Та въпросите за CASE туловете периодично възниква пред мене и ме "гложди" ...

А относно това което предлагаш - за спецялната тема за GCC + Tool-Chain - Определено съм "ЗА". Преди време Цецо, а после и аз във форума повдигахме този въпрос и обсъждахме "за и против" използването на "безплатни" развойни инструменти.
Готов съм да съдействам активно в тази насока.

А за това за преход от "С" към "С++" - зависи мнооого от конкретния проект. В по-големи проекти и такива, които ще "вървят" на платформи с много РАМ и РОМ и производителни процесори и особенно ако имат графика (дисплей) - да-струва си - даже е задължително. Това ще подобри четимостта на кода.
Но за "въшкави" проектчета, които работят в едночипов вариянт и са с ограничени ресурси - определено съм скептичен. Вероятно твоите проекти не спадат в категорията "въшкави" ...