Как да напишем документация, която действително е полезна?

Златните правила за документация на кода

Добрата документация добавя четливост, прозрачност, стабилност и надеждност на вашето приложение и/или API. Но каква е добрата документация? Какви са съставните елементи на добрата документация?

Програмистите обичат да пишат код, но не искат да пишат документация. Разработчиците винаги искат да прочетат документацията, когато наследят проект, но сами да го пишат? Не особено!


Неотдавнашно проучване на GitHub установи, че "непълната или остарялата документация е повсеместен проблем", според 93% от анкетираните. Още 60% от сътрудниците на хранилището с отворен код заявяват, че рядко или никога не допринасят за документацията.

Това не е позиция, която бизнесът ви може да си позволи да приеме. Повечето фирми живеят и умират от софтуера си. Ако сте програмист или мениджър на приложения и не знаете какво всъщност се случва в кода ви, колко стабилен може да бъде бизнесът ви наистина?

През 2016 IEEE установи, че сред 133 популярни проекта на GitHub, 65% 
от разработчиците рядко заявяват, че всичко в техния проект е добре документирано и те рядко твърдят, че всеки знае подробностите поради страхотната комуникация на отбора. Много по-често се чува обратна връзка като "Кой има време да документира всичко?"



За разлика от тях, CIO и други ръководители на ниво C може да мислят, че всичко е под контрол. В изследване, поръчано от Enterprise.Nxt, 57% от 106 респонденти заявяват, че проект, който губи основния си разработчик, ще работи добре и 36 процента смятат, че могат да се справят с малки нарушения.Каква е истината, не е ясно.

Много от тези CxOs споделят убеждението, че един добър ръководител на проекти може да запази софтуерните проекти по пътя към тяхното пускане на пазара.


Все пак, ако искате софтуерът ви да бъде наистина полезен, трябва да документирате приложения и всички взаимосвързани системи. И това не е достатъчно, за да се напише документация. 

 Документацията трябва да е добра, или разработчиците и потребителите ще я игнорират. Кати Сиера, известният автор на Java, веднъж каза: "Ако искате да направят RTFM, направете по-добър FM."


Направете документацията част от процеса на разработката. Не спирайте да коментирате кода. В много компании основната работа на разработчиците e писане, отстраняване на грешки и запазване на кода.
Не разглеждайте документацията като задача, която ще направите "по-късно". Не сте готови, докато приложението не бъде документирано, както на високо ниво, така и за всеки модул.
"Документацията трябва да бъде непрекъснат процес, точно като тестването", казва Арсени Мурзенко, разработчик във Finaxys, софтуерна консултантска компания. "Ако прекарате една седмица, като просто кодирате няколко хиляди реда код, връщането към тестовете без документацията е много, много болезнено".

Процесът на подготовка на презентацията помага на разработчиците да организират мислите си и да решават какво е важно да се предаде. Освен това стилът на презентация и Q & A оспорват предположенията на разработчиците, насърчавайки обясненията, които да бъдат добавени към документацията.


Подхождайте към систематичното кодиране на документацията на кода, докато правите други части от процеса на разработка, за да ви помогне да намерите бъгове, преди те да достигнат производството; трябва да очаквате от други хора да ви дадат отзиви за това дали вашите коментари ви помагат да разберат как да използвате API, който сте написали.

Кодът, който ви е кристално ясен, може да бъде кал за друг разработчик. И само защото днес ви е очевидно какво пишете, след две години няма да си спомните.

Примерите са жизненоважни. Един пример може да запише началото на часовете на чувство на неудовлетвореност. Примерите също показват точно какво сте имали предвид, когато сте написали функция, ако демонстрирате как сте си представяли, че се използва. За по-усъвършенствана документация, като например ръководства, трябва да използвате екранни снимки. Едно изображение може да не струва хиляда думи, но може да помогне.

Добър пример за документация, която се придържа само към необходимите факти, е документът за стартиране на Apache Web Server, който обхваща това, което някой трябва да знае преди да започне проекта.


"Целта е да начертаем линия, което е извън обхвата на документацията, като същевременно насочва хората към ресурси, които действително покриват тези неща в голяма дълбочина и мащаб ", казва Боуен. "Спецификацията HTTP, вътрешната работа на DNS и съдържанието (като HTML и CSS) са твърдо извън обхвата на документацията, но всеки, който използва уеб сървъра на Apache, трябва да знае тези неща".

ОК е да автоматизирате документацията - до точка.

Разработчиците винаги искат инструменти и искат да автоматизират частите, които смятат за скучни или обезпокоителни. В резултат инструментите за автоматизация са привлекателни, защото и затова е удобно да се използва софтуер, за да се обобщи какво прави един блок от код и защото тези резюмета могат да останат актуални, дори когато софтуерът е преработен.

Има инструменти, които могат да дадат на вашите коментари и документация стартиране. Три от най-добре познатите са Doxygen, Sphinx и GhostDoc, разширение на Visual Studio.