Ако вашата документация отнема два кликвания, за да се отвори, тя се свива - тя вече е остаряла

През годините съм работил по всички видове проекти – големи, малки, хаотични, преувеличени, „временни“, предполагаемо добре структурирани и всичко между тях. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Всеки проект За да има документация. претенции Всеки отбор Те ще го актуализират. обещания И всеки разработчик уверено казва: "Не се притеснявайте, ще го напиша по-късно", което, както всички знаем, е еквивалент на документацията, която казва: Чекът е в пощата“. След като видях този цикъл да се повтаря повече пъти, отколкото бих искал да призная, осъзнах нещо просто, но брутално вярно: Документацията оцелява само ако живее възможно най-близо до кода – защото разработчиците (включително и аз) са мързеливи същества. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. И от това дойде друго осъзнаване - основният проблем с остарялата документация е фактът, че повечето екипи не я разглеждат като част от основния цикъл на разработване, оставяйки я за по-късно или за сметка на няколко предварителни спецификации, които вече са имали някъде в Confluence. За да напишете смислена документация, нека първо обсъдим какъв тип документация има за софтуерния компонент: Ways to Document Code (That Developers Might Actually Use) Начини за документиране на кода (което разработчиците всъщност могат да използват) След като приемете, че документацията трябва да живее близо до кода, следващият въпрос е да го структурират. Как На практика открих, че добрата документация не е само един артефакт - това е малка екосистема от слоеве, всяка от които служи на различна цел и аудитория. За този проект, който споменах (написан в Java + Spring Boot), идентифицирахме четири основни типа документи: 1. Client Specs В идеалния случай те са богати на повсеместен език и предоставят кодово-агностични описания на бизнес случаи - с други думи, всичко, от което инженерите се нуждаят, за да разберат проблема. За съжаление, в действителност тези документи често се съхраняват някъде в Confluence, споделят се с екипа в началото на проекта и след това почти никога не се актуализират отново. Не ме разбирайте погрешно: тези документи Важно е са Извличането на знания от експерти в областта трябва да бъде най-висок приоритет за всеки инженерен екип. Но спецификациите се развиват, сроковете натоварват всички и тези оригинални документи бавно, но сигурно се превръщат в остаряла основа. Знанието за променящите се изисквания, крайните случаи и пивотите на проектите в крайна сметка живеят в кода - или по-лошо! - в главите на висшите разработчици. За да се справим с това, спряхме да пишем спецификации в случайни Word файлове или страници на Confluence, предназначени да бъдат забравени и да ги преместим възможно най-близо до първия ред: the code repository. Започнахме да ги съхраняваме като Markdown (.md) файлове вътре в репото, обикновено в докове / папки. В големи микросервизни среди тези документи могат дори да оправдаят специално хранилище, свързано като подмодул на Git. За по-нататъшно четене на подмодулите силно препоръчвам този блог пост - . Линк 2. README – The Front Door for Humans Ако спецификациите на клиентите са енциклопедията, README е предната врата.И все пак, това е една от най-пренебрегваните части от документацията в софтуерните проекти. Иронично е, че почти всяка платформа за контрол на версиите - GitHub, GitLab, Bitbucket - автоматично прави README точно на главната страница на проекта. Това е първото нещо, което всеки разработчик вижда, когато се приземи в хранилището. Един добър README не е незадължителен.Това е единственият документ, който най-вероятно ще бъде прочетен, защото изисква И тъй като се намира в основата на репото, разработчиците са по-склонни да го актуализират, докато работят върху кода. zero clicks Една добре написана README трябва да отговори на най-важните въпроси, които един разработчик има в рамките на първите няколко минути от срещата с проект: Какво прави тази услуга / проект / компонент? - кратка цел и контекстно изявление - няма маркетингов поток. Как да го изпълнявам локално? - инструкции за време на изпълнение, променливи на околната среда, настройка на зависимостта и всякакви конкретни за проекта команди. Как да го тествам? - тестове на единици, тестове за интеграция, настройка на тестови данни и всякакви инструменти, свързани с тестването. Как е структуриран проектът? - кратко обяснение на оформлението на директорията, ключовите модули и къде да намерите важните части на кода. Разполагане скриптове, CI / CD бележки, необходими разрешения, или нюанси на платформата. Къде мога да прочета повече? - връзки към генерирани документи, архитектурни бележки, препратки към API и централизирани документи за проектиране. README е порталът към проекта.Той задава очаквания, намалява времето за включване и дава на всеки инженер – нов или опитен – ясна ориентация.Когато се поддържа правилно, той се превръща в най-ценния единствен документ в цялото хранилище. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - обикновено невидими, често забравени, но абсолютно необходими, когато нещо се счупи. На практика документирането на Java проекти често попада в две крайности: или или Защото „кодът се самодокументира.“ Истината, както винаги, е някъде по средата. over-commenting every trivial line no comments at all За нашия проект взехме съзнателно решение да документираме Това означаваше: only what was genuinely necessary използване на повсеместен език, така че домейн термините да съответстват точно на това, което е в бизнес спецификациите обясняване на причината за неочевидните решения, а не това, което вече разкрива кодексът документиране на ключови класове домейни, интерфейси и сложни работни потоци avoiding comment walls that simply repeat the method name in verbose form JavaDocs, когато се използват правилно, служат като документация на микро ниво, която изяснява намерението, без да обърква кода.И за разлика от страниците Confluence, JavaDocs идват с вградено предимство: Компилаторът всъщност се оплаква, когато излизат от синхронизация. Ако преименувате параметър, но забравите маркера JavaDoc, конструкцията ви напомня. Ако изтриете метод, но оставите остарели препратки към коментари, IDE се осветява като коледно дърво. Това нежно триене е точно защо JavaDocs са склонни да останат по-точни от други форми на документация - те са досадни да се пренебрегва. За да запазим всичко централизирано и да избегнем „документалните острови“, ние също използвахме . Doxygen Доксиген е широко използван инструмент за генериране на документация в разработването на софтуер. Докато се използва главно в общността C++, ние го използваме, за да обединим JavaDocs в последователна, преглеждаема справка - HTML страница. Той има редица функции, които JavaDoc не предлага, например, диаграми на класове за йерархиите и контекста на сътрудничество, повече страници за обобщение и много други. Това ни даде чист, обединен изглед на цялата кодова база, без да разчитаме на разпръснати IDE намеци. 4. Clean Code – The Documentation You Don’t Need to Maintain И накрая, най-подценената форма на документация също е тази, която разработчиците най-малко уважават, докато наистина не се нуждаят от нея: clean code. Коментари възраст. Спецификации дрейф. READMEs се игнорират. JavaDocs могат да станат нестабилни. Но добре написан код – ясен, целенасочен и изразителен – на документацията. е Както знаменито каза дядо Боб, „Чистият код се чете като добре написана проза.“ На практика това означава: Класове и методи с имена, които разкриват тяхната цел Функции, които правят едно нещо и го правят добре Доменната терминология се използва последователно през целия период Никаква мъдрост заради себе си Няма „извънредно поведение“, скрито вътре в страничните ефекти няма ненужно дълбоки абстракции, които изискват докторант да разбере Чистият код е единственият артефакт, който е гарантиран за оцеляване на рефакторите, спринтовете, оборота на персонала и организационния хаос. поведението на системата. is Едно просто правило се появи за нас с течение на времето: If you need a paragraph of comments to explain a method, the real problem is the method. Когато кодът е изразителен, всичко останало става по-лесно → JavaDocs стават по-леки и по-фокусирани → README се свива, защото вграждането става очевидно → спецификациите стават по-ясни, защото моделът на домейна отразява бизнес речника. Чистият код не премахва необходимостта от документация; той Това е. Анкетите Той гарантира, че всички други форми на документация – спецификации, READMEs, JavaDocs – подкрепят истината, вместо да компенсират неясното изпълнение. В края на краищата, чист код е документацията, която не изисква поддръжка, не изисква интегриране на CI и не изисква инструментиране. Bringing It All Together — A Living Documentation Pipeline Вземете всичко заедно - жива документация тръбопровод След като усъвършенствахме начина, по който писахме документацията, последната стъпка беше да гарантираме, че тя не е просто създадена, а непрекъснато доставяна и винаги достъпна. . living documentation portal Тъй като искахме нашите документи да живеят възможно най-близо до нашия код, решихме да разгърнем всичко чрез , което ни даде безпроблемно, управлявано от версии хостинг решение, пряко свързано с кодовата база. Github Pages не е специфичен за Github (GitLab, например, също има GitLab страници) - това е друга чиста функция на популярните системи за контрол на версиите, които препоръчвам за по-нататъшно четене - . GitHub Pages Линк За да съберем всичко в набор от последователни страници, ние използвахме Sphinx. Sphinx е мощен генератор на документация, написан на Python. Той взема изходни файлове, написани в reStructuredText или Markdown и ги превежда в различни изходни формати, включително HTML, PDF и ePub. Sphinx се занимава със структурата, навигацията и тематиката. Doxygen подхранва Sphinx с автоматично генерирани JavaDocs, използвайки В същото време коренът README служи като непосредствена точка за влизане за разработчиците, които изследват репозиторията, като се свързват безпроблемно към генерирания сайт за документация. дишане Всяко сливане в основното предизвика работа на CI, която пресъздаде документите, като гарантира, че порталът отразява последните промени в кода, актуализациите на API и решенията за дизайн. Нищо не живее в изолация. Нищо не изисква ръчно синхронизиране. Това превръща нашата документация от статичен артефакт в непрекъснато актуализирана екосистема, която разработчиците действително използват, защото тя е интегрирана директно в ежедневния им работен поток и живее точно до кода. Conclusion — Documentation Is Our Responsibility, Not Our Burden Заключение — Документацията е наша отговорност, а не наша тежест В края на деня писането на документация не е незадължително. Това е част от нашата работа като инженерни професионалисти. Бъдещите съотборници зависят от него. Включването зависи от него. Поддръжката, надеждността и дори архитектурната яснота зависят от него. Но приемането на тази отговорност не означава, че документацията трябва да бъде болезнена. Чрез поддържане на документи близо до кода, автоматизиране на всичко, което може да бъде автоматизирано, и разчитане на интелигентни инструменти като Markdown, JavaDocs, Doxygen и Sphinx, ние премахваме триенето, което обикновено убива документационните усилия. Когато изграждаме системи, които насърчават разработчиците да актуализират документи толкова лесно, колкото те пишат код, всеки се възползва: от екипа, продукта и най-важното, от бедната душа, която наследява проекта шест месеца по-късно. Добрата документация не ни прави по-малко мързеливи.Това просто прави мързел съвместим с изграждането на голям софтуер.