Att försöka förstå ett GitHub-repository är ett ganska intressant äventyr. Du öppnar ett arkiv och sedan, om du har tur att hitta en anständig Readme-fil, upptäcker du vilka tekniker projektet byggdes med, hur du konfigurerar och startar projektet etc.
"Åh trevligt, projektet använder Node.js och jag kan starta upp det med NPM! Allt finns i readme-filen!" - Naiv programmerare
När du har läst igenom Readme-filen och Wiki-sidorna på go brukar man börja gräva i koden för att förstå hur den är uppbyggd.
Det finns dock en viktig fråga och ett svar som saknas i den genomsnittliga Readme-filen eller Wiki - Varför?
En så enkel fråga, men obesvarad i de flesta projekt.
I den här artikeln kommer jag att presentera idéer och exempel på hur man kan svara på den frågan.
Varför utformades programvaran som den är? Vilka icke-funktionella krav påverkade arkitekturen? Hur mappas dessa beslut till problemområdet och kraven?
Mjukvaruarkitektur är en process; en sekvens av strategiska designbeslut som mappar specifikation och affärsmål till arkitekturdesign
Mjukvaruarkitektur kan vara en explicit eller implicit beslutsprocess, men oavsett tillvägagångssätt har alla system en mjukvaruarkitektur och beslut har fattats baserat på en specifik värdehypotes som ska uppfylla kända krav.
Traditionellt handlar programvaruarkitektur om funktionella och icke-funktionella krav (riktigt dåligt namn) och att omvandla dem till en uppsättning designbeslut som påverkar arkitekturen.
Men det är inte allt. Artefakter för programvaruarkitektur är också en kommunikationsmetod. De är ett sätt att öka förståelsen och samsynen mellan teammedlemmarna.
Många förknippar mjukvaruarkitektur med komplexa diagram och dokumentation, men det är inte vad jag pratar om i den här artikeln.
Jag vill föreslå att du använder en mycket smidig artefakt som du enkelt kan producera och underhålla i Github - en checklista för "designbeslut".
Denna checklista redogör för skälen till varför du valde att go gå i en viss riktning med din arkitektur. Det är ett effektivt kommunikationsverktyg som gör det möjligt för dig att tänka och kommunicera på ett strukturerat sätt.
Här är ett exempel som är hämtat från Ryan Dahls ursprungliga Node.js whitepaper från 2009:
Node.js Designbeslut - a.k.a. Varför?
Detta är en lista över designbeslut för att stödja version 0.2 av Node.js-biblioteket
Underhållbarhet
Vi vill göra det enkelt att arbeta med asynkron IO
Ingen funktion ska direkt utföra I/O. Använd callbacks istället
Har inbyggt stöd för viktiga protokoll (TCP, DNS, HTTP) och stöd för många HTTP-funktioner (chunked requests, keep alive, comet etc.)
API:et ska vara bekant både för JS-programmerare på klientsidan och för UNIX-hackare av den gamla skolan.
Vara plattforms-/operativsystemoberoende
Återanvänd solida plattformar (Google V8) och minimera beroenden (endast python)
Använd JavaScript eftersom det är utformat för att användas i en event-loop
Skalbarhet
I/O måste göras på ett annat sätt än i traditionella system. Andra exekveringstrådar bör köras medan de väntar. Vi är inspirerade av NGinx och event-loopen.
Strömma allt; tvinga aldrig fram buffring av data
Obs: Dessa beslut är kopierade från den ursprungliga Node.js-artikeln av Ryan Dahl och anpassade till detta format.Designbeslut - Node.js 2009
Jag tror att när man läser designbesluten ovan är det mycket tydligare vad som är målet med Node.js och varför Ryan Dahl valde JavaScript och event-loopen när han designade Node.js.
Väldigt få projekt formulerar tydligt varför de gör som de gör, och det är den delen som saknas.
Tänk dig att ha en trevlig checklista som ovan i varje projekt i GitHub! Det skulle vara en fröjd att förstå och bidra till projekt.
Vad är det första en programmerare gör när han inte förstår ett projekts arkitektur efter några dagar? Han funderar på att refaktorisera det eller skriva om det.
Att ha ett tydligt dokument med designbeslut är ett sätt att förklara varför systemet utformades som det gjorde och att formulera specifika avvägningar som du gjorde.
Ibland är det svårt att hålla alla kvalitetsegenskaper på samma nivå. Det är t.ex. välkänt att fokus på hög prestanda och skalbarhet måste betalas med lägre underhållbarhet. Det är en vanlig avvägning, men om den inte dokumenteras kan den missförstås om man bara tittar på koden.
"Varför använder han den här kön i koden? WTF! den här programmeraren är en idiot. Jag måste skriva om den här koden" - Clueless programmerare
Om besluten dokumenteras i ett dokument blir de lättare att förstå och risken minskar för att nästa utvecklare ska förbanna dig på nätterna. Designbeslut kastar ljus över de mest komplexa delarna av arkitekturen och hjälper nästa utvecklare att leva ett lyckligare liv.
Programmering av religionskrig startar ofta på grund av missförstånd och man kan förhindra det med öppenhet.
Designbeslutsdokument ger en bra nivå av ärlighet om din programvaruarkitektur för ditt framtida jag eller personer som kommer efter dig för att underhålla koden.
Ibland måste man göra avvägningar för att öka produktiviteten eller leveransen, och det är helt okej så länge man dokumenterar det.
En välkänd metod för att bygga upp nystartade företag är till exempel att använda den teknik som man är mest bekant med, vilket inte nödvändigtvis är något som en mjukvaruarkitekt på ett företag skulle förstå och godkänna.
En utvecklare som inte är bekant med den här mentaliteten skulle bli väldigt förvånad över att öppna ett GitHub-arkiv och upptäcka att Ruby on Rails användes för system X även om det helt klart är "inte skalbart", men det kan finnas ett sätt att dokumentera beslutet så att det blir förståeligt för den puritanska programvaruarkitekten. Här är ett exempel:
Project MVP - Design Decisions - a.k.a. Why?
This is a list of design decisions to support the MVP of our product.
Maintainability
We prioritize productivity and time to market, so we plan to use Rails since the team is familiar with the technology even if it might be suboptimal.
Skip automated tests because of lack of time and money for the MVP
Scalability
We expect from 500-2000 active users using our systems daily. This should be easily achievable with a modest deployment in Google Cloud and Kubernetes.
Performance
We want to have < 1s response times on every page in our system
Fault-Tolerance
Our systems should restart automatically in case of a failure. We plan to use Docker and Kubernetes.
Security
Our systems should be protected against the top 10 OWASP vulnerabilityDesignbeslut - Node.js 2009
Ärlighet är bra, och det kan spara många besvär och omarbetningar. Du kan till och med gå ett steg längre med ” go ” och ta med de saker som du hade tänkt att inkludera i din design men inte hann med.
En bra riktlinje för att strukturera checklistan är att utgå från vanliga systemkvalitetsattribut. Om du vill go gå ett steg längre kan du till och med dela upp dokumentet med designbeslut i två avsnitt: Icke-funktionella krav och Designbeslut. Kortfattadhet är dock alltid att föredra, eftersom ingen gillar att läsa långa dokument.
Poängen med att hålla dessa dokument i GitHub och inte i Confluence och liknande dokumentationssystem är att dokumentation blir gammal och vanligtvis slutar inte underhållas. Genom att hålla det enkelt och smidigt i GitHub markdown-filer finns det en större chans att överleva tidens gång och hålla dokumentet uppdaterat.
För de mer avancerade utövarna av dokumentation av arkitektoniska beslut är ADR ett projekt som försöker standardisera dokumentation och underhåll av arkitektoniska beslut i dina arkiv.
En "lättviktig" ADR består av titel, status, sammanhang, beslut och konsekvenser
För ytterligare läsning, se deras webbplats:
Jag tror att det skulle göra programmering mycket roligare att ha arkitektoniska designbeslut i GitHub-arkiv och att det skulle öka förståelsen och förmågan att lära sig hur man underhåller okända projekt. Det skulle också kunna vara mycket användbart för projekt med öppen källkod.
Eftersom de flesta programmerares liv går ut på att underhålla befintlig kod (och inte skriva ny kod) tror jag att det är viktigt att tänka på att göra det lite enklare för alla inblandade. Hjälp dig själv och dina kollegor att lyckas!