Proqram mühəndisləri arasında geniş yayılmış bir yanlış anlayış var: sənədləşmə (dokumentasiya) işin sonunda, PR birləşdirilməmişdən əvvəlki son 20 dəqiqədə yazılan bir README faylı kimi qəbul edilir. Məqalə müəllifinin vurğuladığı kimi, bu yanaşma səhvdir. Sənədləşmə memarlığın təsviri deyil, memarlığın özünün bir hissəsidir. Onu ayrı bir şey kimi qeyd etmək, bütün testlərdən keçən, lakin iç-içə çürümüş sistemlərin yaranmasına səbəb olur.
Kompilyator (və ya interpretator) yalnız bir növ düzgünlüyü yoxlayır: kodun göstərişlərinə uyğun işləyib-işləmədiyini. Bəs niyə müəyyən bir cədvəldə deleted_at sütunu var, yoxsa hard silmə? Niyə xidmət 3 dəfə eksponensial back-off ilə cəhd edir, 5 dəfə sabit interval ilə yox? Bu qərarların arxasında tənzimləyici, tarixi və ya performans məhdudiyyətləri ola bilər. Əgər bu məntiq yalnız o kodu yazan proqramçının beynində qalırsa, memarlığın bir hissəsi sənədsiz qalır və növbəti təcili dəyişiklik zamanı həmin məhdudiyyətlər pozulur.
Dizayn sənədləri niyə vacibdir?
Yaxşı sənədləşmə tətbiqdən əvvəl və ya onunla eyni vaxtda yazılmalıdır, sonra yox. Bir dizayn sənədi hazırlayarkən problemi, nəzərdən keçirdiyiniz variantları, seçdiyiniz həlli və etdiyiniz güzəştləri (trade-off) açıq şəkildə qeyd etmək əslində real dizayn işidir. Müəllif deyir ki, “niyə X deyil” bölməsini yazarkən yanlış fərziyyələrə düşmək, kod rəyi (code review) zamanı olduğundan daha çox baş verir. Çünki PR gələnə qədər tətbiqə sərf olunan vaxt və səy, rəyçilərin yanaşmanı sorğulamasını çətinləşdirir.
Buna görə də qeyri-trivial dəyişikliklər üçün dizayn sənədləri məcburi sayılmalıdır. Sənəddə kodun sadəcə təsviri deyil, tətbiq edilən və ya qorunan invariantlar (məsələn, yeni Go xidməti üçün idempotentlik, FastAPI endpoint'inin eyni sorğunun təkrarına davamlı olması) qeyd olunmalıdır.
ADR-lər: gələcəkdəki suallara cavab
Memarlıq Qərar Sənədləri (Architecture Decision Records – ADR) bu səbəbdən işləyir. Onlar təkcə nəticəni deyil, düşüncə formasını da sənədləşdirir. 18 ay sonra kimsə “niyə aşkar olanı etməmişik?” deyə soruşanda, qısa bir ADR (kontekst, qərar, nəticələr – üç paraqraf) cavab verir. Əgər bu tarixçə olmasa, kimsə Allahın işi kimi görünən bir məntiqi sınayar, heç kimin xatırlamadığı struktur əhəmiyyətli bir şeyi pozar və dəyişiklik səhər saat 2'də geri qaytarılar.
Bu xüsusilə kiçik komandalar və tək layihələr üçün kritikdir. Müəllif öz təcrübəsindən nümunə verir: Bitcoin/Lightning ilə bağlı öz repolarını yenidən açarkən commit mesajlarının nəyin dəyişdiyini göstərdiyini, lakin niyə müəyyən bir timelock dəyərinin seçildiyini izah etmədiyini görüb. Üç paraqraflı bir ADR ona həftələrlə vaxt qazandıra bilərdi.
Daha güclü bir versiya isə budur: sənədləşmə təkcə memarlığı sənədləşdirmir, həm də onu gücləndirir. Dizaynı heç bir konteksti olmayan bir oxucuya izah etməyə çalışmaq, ən yaxşı dizayn-rəy texnikalarından biridir. Əgər bir xidmətin niyə müəyyən məlumatlara sahib olduğunu izah etmək çətindirsə, çox güman ki, sərhədlər səhv çəkilib. API-i üç istisna və bir dipnotla izah etmək məcburiyyətindəsinizsə, o API-in kontraktı ardıcıl deyil, sadəcə az sənədləşdirilib. Sənədləşmə borcu ilə memarlıq borcu əslində eyni borcdur – birini ödəmək digərini də ödəyir.
Bütün bunlar ağır proseslər tələb etmir. Kiçik komanda və ya tək layihə üçün yaxşı təcrübə: geri qaytarılması baha başa gələcək hər qərar üçün bir səhifəlik ADR, ilk baxışda səhv görünməyən yerlərdə kodda inline şərhlər və əsas komponentlərin məsuliyyəti dəyişdikdə beş dəqiqəlik yeniləmə alan canlı memarlıq sənədi. Gözəl formatlanmış, amma heç vaxt yenilənməyən viki səhifələrindən daha yaxşıdır. Sənədləşməni birinci dərəcəli dizayn aləti kimi qəbul edin, memarlıq faydası da öz-özünə gələcək.
Mənbə: Dev.to (https://dev.to/meroline_lizlent/why-documentation-is-architecture-1mb7)
