Može li mi netko kao se vodi dokumentacija za neki programski projekt odnosno ima li to smisla uopće voditi? Što se u tu dokumentaciju uopće zapisuje? Zapisujem li tu mehanizme na kojima se aplikacija bazira? U kojem formatu to trebam čuvati(pdf,rtf,txt ili nešto treće)?
- +/- sve poruke
- ravni prikaz
- starije poruke gore
Dokumentacija za aplikaciju je dosta složen pojam koji može podrazumijevati puno toga, no uglavnom se odnosi na osnovni opis aplikacije i njenih dijelova. Možeš pogledati kako sam ja to napravio u ovoj aplikaciji.
projektna dokumentacija je jako važan dio svakog projekta.
manje je važan način vođenja, puno je važnije da se sve vodi, bilježi, dokumentira.
mora svakome i za 3 godine biti jasna svrha nekog algoritma ili neke opcije ili zašto baš ta implementacija nekog procesa, a neka druga i sl....
projektna dokumentacija je jako važan dio svakog projekta.
manje je važan način vođenja, puno je važnije da se sve vodi, bilježi, dokumentira.
mora svakome i za 3 godine biti jasna svrha nekog algoritma ili neke opcije ili zašto baš ta implementacija nekog procesa, a neka druga i sl....
Na ovaj tip sam dokumentacije mislio. No nije mi jasno na koji bi način to trebao voditi? Jer pretpostavljam da bi ta dokumentacija trebala ostati jasna i precizna onome tko to bude čitao za tri godine. U kojem ću formatu to uopće čuvati?
Na ovaj tip sam dokumentacije mislio. No nije mi jasno na koji bi način to trebao voditi? Jer pretpostavljam da bi ta dokumentacija trebala ostati jasna i precizna onome tko to bude čitao za tri godine. U kojem ću formatu to uopće čuvati?
Jedan dio toga definitivno ide u izvorni kod putem komentara, doxygen ti od toga može složiti nekakav dokument. Stvar je prilično jednostavna. Samo zamisli da ćeš ti to morati za 3 godine sve opet gledati kada si već većinu toga zaboravio, i onda ti ta dokumentacija posluži da u njoj pročitaš što si i zašto negdje nešto radio.
Evo ti primjer developer dokumentacije Blendera (ono što ti vjerojatno želiš je pod "Architecture")
Slično imaš i za Mozilline projekte samo što trebaš malo više kopati da bi došao do onoga što želiš.
Što se formata tiče, on je tu manje bitan, .txt, .pdf, .doc, .html, pa čak i papir, svejedno je.
Jedan dio toga definitivno ide u izvorni kod putem komentara, doxygen ti od toga može složiti nekakav dokument.
Ok. Sada sam pokusao sve dokumentirati pomocu komentara i moze li mi netko pogledati kod i reci radim li to pravilno?
File: calcex_algebra.h
/*Calcex algebra library - header file
*--------------------------------------------------------
*Library contains most used algebra functions.
*--------------------------------------------------------
*Version 0.1
* -added 4 functions:
*Author: Capttawish
*--------------------------------------------------------
*
*/
#ifndef CALCEX_ALGEBRA_H_INCLUDED
#define CALCEX_ALGEBRA_H_INCLUDED
/*returns a square root of number. It take only nonegativane number,
*optionaly precision in decimal places(default 2)*/
extern double CALC_sqrt(const double number,const unsigned int precision=2);
/*takes an integer and return factorial of that integer*/
extern long CALC_factorial(unsigned long n);
/*takes base, and optionaly exponent(default 2), returns potention*/
extern double CALC_pow(double base,int exp=2);
/*takes number an returns absolute value of that number ,*/
extern inline int CALC_abs(int number);
#endif // CALCEX_ALGEBRA_H_INCLUDED
File: calcex_algebra.cpp
/*Calcex algebra library - header file
*--------------------------------------------------------
*Library contains most used algebra functions.
*--------------------------------------------------------
*Version 0.1
* -added 4 functions
*Author: Capttawish
*--------------------------------------------------------
*
*/
/*takes number an returns absolute value of that number ,*/
inline int CALC_abs(int number){
return number > 0? number : -number;
}
/*takes base, and optionaly exponent(default 2), returns potention*/
double CALC_pow(double base,int exp = 2){
double solution = 1;
int tExp = CALC_abs(exp);
while(tExp){
if(tExp & 1) solution*=base;
base *= base;
tExp >>= 1;
}
return exp>=0 ? solution : 1./solution;
}
/*returns a square root of number. It take only nonegativane number,
*optionaly precision in decimal places(default 2)*/
double CALC_sqrt(const double number,const unsigned precision = 2){
double downLimit = 0, upperLimit = number >= 1 ? number : 1;
double limitDifference = 5 * CALC_pow(10,-(precision + 2));
while(upperLimit - downLimit > limitDifference){
double middle = (upperLimit + downLimit)/2;
if(middle*middle > number)
upperLimit = middle;
else
downLimit = middle;
}
return (upperLimit+downLimit)/2;
}
/*takes an integer and return factorial of that integer*/
long CALC_factorial(unsigned long n){
long solution = 1;
for(unsigned i = 1;i<=n;i++)
solution *= i;
return solution;
}
Djeluje ok. Opisao si što ulazi u funkcije i što iz njih izlazi, kod većih funkcija i kompliciranijih algoritama bi bilo dobro i opisati algoritam u kratkim crtama, te ako nije posve jasno, objasniti namjenu neke funkcije te zašto je napisana baš tako a ne nekako drugačije...
Gledaj to ovako, ja i ti radimo zajedno na nečemu. Ja poslije tebe čitam i dorađujem tvoj kod, ti mi u kodu ostavljaš komentare koji mi opisuju gdje je što, i zašto baš "ovako" a ne "onako".
Vježbom do savršenstva. A ne bi bilo loše da si nađeš nekakav dobro komentirani open source projekt pa vidiš kako to u praksi ljudi rade. Što više toga budeš vidio, dobit ćeš bolju sliku o tome.
Evo ti nešto da pogledaš situaciju iz drugog kuta:
-nema pogrešnog načina. .. ali, kad već koristiš REMove treba ih uredno (estetski) koristiti. Kao i npr intendancija samog koda.
-za primjer pogledaj razne batcheve by MS i ostalih firmi, u header može firma/dev, godina, copyright.. dok se npr odlomci mogu odvajati ovako:
************************************
-ovo je 'siromašnjiji' primjer
-naravno, dodati asterixe i sl. ***
::: ili kombinaciju ----_______::*** ..
************************************
- preporuka notepad++, graničnik na 80, intendancija 4, replace tab with space, nikad pisati od početne lijeve pozicije nego uvučeno itd..
To sve štedi živce i olakšava rad na većim-dugotrajnim projektima (update-patch-revizije..). Isplati se držati uredno / samoobjašnjavajuće...
Kao i (nekome) bitno kod mogućih sporeva oko vlasništva nad softwareom.
Koji programi su user friendly za vođenje dokumentacije za projekt ? Trebao bi imati mogućnost izrade ' directory tree of a folder ' projekta te postavljanje ' Comment/Notes ' za svaki folder i dokument koji se nalazi u projektu. Imam folder s prostornim podacima (topo karte, shp file, prostorni planovi) te excel tablice s numeričkim-atributnim obilježjima. Isprobao sam voditi u wordu i visio ali mi smeta ograničenje prostora za izradu directory tree projekta.
teško da ćeš sve te želje ispuniti nekim drugim office pakeotm, prilagodi se.. :) ili problemi s povezanim doc/kompatibilnosti i 'raspadanju'..