Dobra dokumentacja na wagę złota

Uwaga! Informacje na tej stronie mają ponad 5 lat. Nadal je udostępniam, ale prawdopodobnie nie odzwierciedlają one mojej aktualnej wiedzy ani przekonań.

# Dobra dokumentacja na wagę złota

Fri
13
Apr 2007

Dokumentacja... Najbardziej znienawidzona część każdego programu. Prawie nikt nie lubi jej pisać, ale wszyscy wiedzą, że jest niezbędna. Dokumentacja jest tym, co najlepiej odróżnia prawdziwy, dopracowany program od eksperymentu/prototypu.

Dla odbiorcy danego programu (czy - przede wszystkim - biblioteki) dobra dokumentacja to nieoceniona pomoc. Zaawansowani tym się właśnie różnią od początkujących, że nie boją się do niej zaglądać, bo wiedzą, że znajdą tam systematyczny i szczegółowy opis każdej funkcji, jej działania i parametrów. Tylko czy na pewno kompletny?

MSDN zawsze pozostaje dla mnie pod tym względem wzorem. Ale już dokumentacji w DirectX SDK można co nieco zarzucić, szczególnie jej części poświęconej D3DX. Oprócz braku rozdziałów opisujących ogólnie sposób używania poszczególnych interfejsów doskwierają liczne drobiazgi. Na przykład:

D3DXMACRO Macros[MACRO_COUNT+1];
for (int i = 0; i < MACRO_COUNT; i++) {
  Macros[i].Name = // ...
  Macros[i].Definition = // ...
}
Macros[MACRO_COUNT].Name = NULL;
Macros[MACRO_COUNT].Definition = NULL;

Comments | #directx #philosophy #software engineering Share

Comments

STAT NO AD
[Stat] [STAT NO AD] [Download] [Dropbox] [pub] [Mirror] [Privacy policy]
Copyright © 2004-2019