Jaderné noviny – 23. 11. 2011: Ovladače jako dokumentace (diskuse)

[xkucf03]

Sice nepíšu ovladače do jádra, ale tohle moc dobře znám:

Chvilka strávená dokumentováním bitu ... může ušetřit někoho dalšího od hodin zbytečné bolesti.

A nemusí jít jen o bity

[koudy]

Vy se neridite "Bylo to tezke naprogramovat, tak to musi byt tezke i pochopit?"

Nejlepsi jsou komentare ke kodu, ktere jsou zkopirovany s castmi kodu z jineho mista.

To pak tak "krasne" zprehledni a zjednodusi pochopeni.

[Sten]

Nejlepší komentáře jsou „Dirty hack“ bez vysvětlení proč a jak a „You’re not supposed to understand this“.

[Michal Kubeček]

Aspoň že tam není ještě "Neither do I." :-)

[cronin]

Pravdepodobne narážal na slávny komentár Knuth-a v zdrojákoch TeX-u pri premetoch s file deskriptorom 3.

[Sten]

Ten slavný komentář Donalda Knutha měl alespoň předtím popsáno, jak to funguje. Ale jsou i lidé, co si myslí, že jsou další Knuth, a tak to rovnou napíšou bez vysvětlivek :)

[olgo]

Jaderný kód je prověřován z hlediska funkčnosti, dlouhodobé udržovatelnosti, dokumentace a ještě více.

Pokud zdrojový kód ovladače novému vývojáři nepomůže, mohli bychom se dohadovat, že původní autor zklamal očekávání.

Jak čas utíká, začíná se lépe chápat problém a termíny se blíží, tak návrháři hardwaru začínají zahazovat funkce, které už nejde stihnout, nebo ty, které podle svého vlastní názoru, proti kterému není odvolání, lze snadno dořešit v softwaru.

[luta]

jo na te dokumentaci neco bude.. ono pak nepotesi najit v driveru komentar typu  /* magic number */

[Bluebear]

Zrovna komentář "magic number" mi připadá jako ještě poměrně stravitelný - to si interpretuju jako "nemám ponětí, co to dělá, ale dlouhým zkoumáním jsem zjistil, že tento registr musí mít vždy tuto hodnotu, jinak se to celičké po*ere"

[R]

Magicke cisla sa vyskytuju hlavne v driveroch, ktore vznikli bez dokumentacie, odchytavanim komunikacie binarneho drivera s HW. iekedy sa da zistit alebo odhadnut, co ktore cislo znamena (bity nejakeho registra alebo cisla prikazov). Niekedy nie a potom to ostane ako magicke cislo.