Programowanie/Podstawowe konstrukcje/Dokumentowanie

Program jest tak dobry jak jego dokumentacja.

Dokumetowanie

edytuj

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.:

  1. poszukiwanie błędów, weryfikacja poprawności
  2. próba rozmaitych usprawnień kodu
  3. 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)

edytuj

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

edytuj

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

edytuj

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

edytuj

Mogą być tworzone za pomocą grafiki ASCI ( ang. ASCII graphic):[3] lub grafiki Unicode [4]


        +---------+
        |         |                        +--------------+
        |   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  │
               └─────────┘       └─────────┘


Narzędzia do tworzenia dokumentacji

edytuj

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

edytuj