Programowanie/Podstawowe konstrukcje/Dokumentowanie

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, ^[1]
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.^[2]

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):^[3] lub grafiki Unicode ^[4]

ręcznie^[5]
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 ^[6]


  ┌─head─┐     ┌──value──┐       ┌──value──┐
  │   ├───────►│    4    │       │    0    │
  └──────┘     ├───next──┤       ├───next──┤
               │    ├───────────►│   NULL  │
               └─────────┘       └─────────┘

prosty
skomplikowany

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

[1] Typy komputerów w wikipedii

[2] teusz Skalski: naming-conventions

[3] Explaining Code using ASCII Art by John Regehr

[4] Box-drawing_character in english wikipedia

[5] unix.stackexchange question: creating-diagrams-in-ascii

[6] stackoverflow question: i-dont-understand-how-this-code-replaces-the-head-of-a-linked-list-or-how-to ?

[1]

[2]

[3]

[4]

[5]

[6]