Blog naukowy. Zdobądź wiedzę z języków obcych, jazdy na łyżwach...

Zasada samodokumentowania programów

Schemat blokowy to najbardziej przereklamowany element dokumentacji programu: szczegółowy schemat blokowy jest dziś czymś zupełnie przestarzałym w wyniku pisania programów w językach wysokiego poziomu (schemat blokowy to wykreślny język wysokiego poziomu).

Do niewielu programów jest potrzebny schemat blokowy mieszczący się na więcej stronach niż jedna. [Wymagania dokumentacji MILSPEC są pod tym względem naprawdę błędne]. Schemat struktury programu jest istotnie przydatny: do rysowania go nie są jednak potrzebne normy tworzenia schematów blokowych, opracowane przez ANSI.

Aby na bieżąco aktualizować dokumentację, należy włączyć ją do programu źródłowego, a nie traktować jak coś odrębnego. W celu zminimalizowania ciężaru przygotowania dokumentacji należy skorzystać z trzech wskazówek:

Zrobić wszystko, żeby te części programu, które i tak muszą być w dokumentacji uwzględnione, jak nazwy i deklaracje, przekazywały użytkownikowi jak najwięcej informacji:

Maksymalnie wykorzystać miejsce i format do przedstawienia wszystkich podporządkowań i zagnieżdżeń oraz do zwiększenia czytelności: włączyć niezbędną dokumentację tekstową do programu w postaci komentarzy, a zwłaszcza jako nagłówki modułów.

W dokumentacji przeznaczonej dla osób, które muszą modyfikować program, należy wyjaśnić, dlaczego coś jest takie, jakie jest, zamiast ograniczać się do stwierdzenia, jakie jest. Kluczem do zrozumienia jest cel programu: nawet składnia języka wysokiego poziomu nie oddaje w pełni celu programu.

Zasada samodokumentowania programów znajduje największe zastosowanie i jest najskuteczniejsza w wypadku języków wysokiego poziomu stosowanych z systemami dostępnymi bezpośrednio – narzędzi, z których powinno się korzystać.

Podobne Artykuły

Zostaw odpowiedź

Twoj adres e-mail nie bedzie opublikowany.