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:

• Czy do funkcji D3DXVec3Normalize albo D3DXMatrixInverse można podać ten sam wektor/macierz jako wejście co jako wyjście? (Tu akurat wiem że można, bo podpatrzyłem w źródłach DirectX-a kiedy miałem do nich dostęp.)
• Czy D3DXCreateEffect w razie błędu zawsze zwraca ppCompilationErrors a nigdy nie zwraca ppEffect?
• Skąd miałem domyślić się, że w D3DXCreateEffectCompiler parametru pDefines używa się tak (autentyczny problem z wczoraj, rozwiązanie znalazłem z pomocą Google na jakimś forum):

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