Program jest tak dobry jak jego dokumentacja.
Dokumetowanie
W programowaniu bardzo ważne jest staranne dokumentowanie swojej pracy. Programowanie wymaga dyscypliny. Dobre programowanie wymaga wiele dyscypliny.
Często kod musi być wielokrotnie, przeglądany przez różne osoby w różnych celach np.:
poszukiwanie błędów, weryfikacja poprawności próba rozmaitych usprawnień kodu inspekcja w celu zbadania jakości kodu
Dobrze udokumentowany projekt jest znacznie łatwiejszy w późniejszym utrzymaniu. Wkład pracy związany z tworzeniem dokumentacji zwraca się bardzo szybko. Znane są przypadki projektów, które upadły z powodu trudności z usunięciem błędów. Dobra dokumentacja pomaga w usprawnieniu kodu, lub jego nowszych wersji.
Elementy dokumentacji Opis programu ( specyfikacja) odpowiednio dobrane nazewnictwo ( funkcji, zmiennych, ...) Komentarze w kodzie programu diagramy przepływu
Opis programu ( specyfikacja) Specyfikacja programu opisuje jego cechy. Pozwala to na lepsze zrozumienie programu. Nie musimy wypełniać wszystkich cech, ale im więcej tym lepiej.
Specyfikacja programu: język mówiony( polski, angielski, ...)- dotyczy komentarzy, opisów, dokumentacji, nazw język programowania (pascal / delph, c, c++, c#,...)- dotyczy kodu źródłowego kompilator IDE styl progrmowania ( Paradygmat programowania): proceduralne, obiektowe, ... metoda programowania : visual (Rapid application development RAD), Metodyki tworzenia oprogramowania : kaskadowy, ... typ interfejsu użytkownika: CLI, GUI, WUI, ... biblioteki GUI : GFLW3, SDL2, ... licencja : GPL/Mozilla/shareware/commercial ... cel ( który procesor wykonuje kod): CPU, GPU Liczba wątków / procesów system operacyjny (OS) : DOS, windows ( 95,98, ME, 2000, XP), linux, MacOS, wieloplatformowy platform sprzętowa ( CPU i architektura): i386, i586, typ komputera type: PC, Typy komputerów w wikipedii data ( utworzenie programu, poprawek) żródło ( adres internetowy repozytorium, strony domowej programu) autor
Przykład:
{ spoken language: english programming language: Pascal ( Borland object Pascal ) compiler: VER 140 IDE: Borland Delphi 7.0 personal edition programming style : objective programming method : visual (RAD) target: CPU number of microprocessors : 1 ; threads : 1 library: standard = VCL program type : GUI application licence: GNU GPL ; see http://www.gnu.org/copyleft/gpl.html OS: win32 (windows 98 SE hardware: PC platform:i386 author: Walbrzych/Poland/EU/europe/earth/Solar System/Milky Way/Universe (:-))) 2009.09.25 }
komentarze w kodzie programu
Z tego powodu w kodzie źródłowym programista może umieszczać komentarze. Komentarze są napisami o specjalnej składni. Są one ignorowane przez kompilator, stanowią natomiast cenną informację dla osób przeglądających kod programu. Pamiętaj że odpowiednio dobrane nazewnictwo może spowodować, że kod sam będzie się dokumentował, tzn, będzie potrzebował mniej komentarzy.ateusz Skalski: naming-conventions
Komentarze w języku C
W języku C istnieją dwa rodzaje komentarzy. Pierwszy rodzaj (starszy) polega na umieszczeniu tekstu komentarza pomiędzy napisami "/*" oraz "*/". Komentarz tego typu może zawierać wiele wierszy.
przykłady:
/* to jest komentarz. */
/* To też komentarz. W kilku liniach. */
/* ===== To także jest komentarz. Bardziej wytłuszczony ===== */
/***********************************
* Bardzo wytłuszczony komentarz *
************************************/
Drugi rodzaj komentarzy (zaczerpnięty z języka C++) rozpoczyna się znakami "//" i rozciąga do końca wiersza.
przykłady:
//to jest komentarz jednowierszowy
// komentowanie w wielu wierszach // jest możliwe jedynie // przez rozpoczynanie // każdej linii komentarza // znakami "//"
//============================================================================== // graficzna separacja fragmentów kodu
Przykłady zastosowania komentarzy.
Lekki komentarz opisujący niewielki fragment kodu:
//tu będzie drobna operacja wykonajDrobnaOperacje();
Większy komentarz na początku programu. Opisuje podstawowe informacje o programie. Generalnie przykład dla ilustracji, drobiazgowe informacje można podać w załączonej dokumentacji.
/* * Program PODATEK DELTA * wersja: 4.16.3 * autor: Jan Kowalski * data: 03.03.2016 * jezyk programowania: C99 * kompilator: GNU gcc * kompilacja: gcc main.c -o prog.out * co program robi: Program oblicza podatek dochodowy dla osób fizycznych za rok 2016 * metoda obliczania: na Korwina (wypowiedz z dnia 12 lipca 2016r. w Parlamencie Europejskim, godz. 12:12 GMT -1) * licencja: GNU General Public License v.3 * wykryte błędy: nie było reklamacji */
Stosowanie komentarzy będzie opisywane podczas nauki. Diagramy przepływu
Mogą być tworzone za pomocą grafiki ASCI ( ang. ASCII graphic):Explaining Code using ASCII Art by John Regehr lub grafiki Unicode Box-drawing_character in english wikipedia ręcznieunix.stackexchange question: creating-diagrams-in-ascii za pomocą specjalistycznych programów gnuplot ( set terminal dumb ) online asciiflow textik
+---------+ | | +--------------+ | NFS |--+ | | | | | +-->| CacheFS | +---------+ | +----------+ | | /dev/hda5 | | | | | +--------------+ +---------+ +-->| | | | | | |--+ | AFS |----->| FS-Cache | | | | |--+ +---------+ +-->| | | | | | | +--------------+ +---------+ | +----------+ | | | | | | +-->| CacheFiles | | ISOFS |--+ | /var/cache | | | +--------------+ +---------+
-- https://rosettacode.org/wiki/Visualize_a_tree -- Vertically centered textual tree using UTF8 monospaced -- box-drawing characters, with options for compacting -- and pruning.
-- ┌── Gamma -- ┌─ Beta ┼── Delta -- │ └ Epsilon -- Alpha ┼─ Zeta ───── Eta -- │ ┌─── Iota -- └ Theta ┼── Kappa -- └─ Lambda
Grafika Unicode stackoverflow question: i-dont-understand-how-this-code-replaces-the-head-of-a-linked-list-or-how-to ? ┌─head─┐ ┌──value──┐ ┌──value──┐ │ ├───────►│ 4 │ │ 0 │ └──────┘ ├───next──┤ ├───next──┤ │ ├───────────►│ NULL │ └─────────┘ └─────────┘
Narzędzia do tworzenia dokumentacji
Przy większych projektach dobrze jest ułatwić sobie przeglądanie kodu. Służą do tego automatyczne generatory dokumentacji.
Programy darmowy generator Doxygen. Pozwala na wygodne i szybkie przeglądanie większych ilości kodu. Do celów edukacyjnych nie jest niezbędny. Zostanie opisany w dalszym ciągu nauki.
Przypisy