V Silicon Valley, ak náhodne zastavíte programátora na ulici a pýtate sa: "Pred začatím projektu, čo by ste mali urobiť?" deväť z desiatich pravdepodobne odpovie: "Napíšte návrhový dokument." a je zdieľaný súbor medzi inžiniermi, ktorý opisuje funkciu, ktorá sa má implementovať predtým, ako sa napíše akýkoľvek kód, ako v Dizajnové dokumenty sa často skladajú z viacerých sekcií: design document (design doc) Tento príklad Tento príklad Prehľad: Niekoľko jednoduchých viet popisujúcich funkciu, ktorá sa má implementovať. Motivácia: Prečo implementujeme túto funkciu? Preview: Ako bude funkcia vyzerať po implementácii? Technické možnosti: Aké technické možnosti musíme implementovať túto funkciu? Aké sú výhody a nevýhody každej z nich? Ktorú sme si vybrali a prečo? Podrobnosti o implementácii: Zoznam šablón kódu, ako testovať, ako písať denníky atď. Je dôležité poznamenať, že projektový dokument by mal zostať na vysokej úrovni; špecifická implementácia je úlohou kódu. Primárny autor zostavuje návrhový dokument a ich kolegovia komunikujú s autorom komentovaním dokumentu.Tento celý komunikačný proces často trvá niekoľko dní alebo dokonca týždňov.Keď sa autor a kolegovia dohodnú na obsahu dokumentu, môže byť zlúčený do kódovej základne.Toto tiež označuje začiatok projektu opísaného v návrhovom dokumente. Tento proces začleňovania projektových dokumentov do projektov ponúka množstvo výhod. Ak môžete vyjadriť svoje myšlienky v stručnom, logicky jasnom jazyku, naznačuje to hlboké pochopenie implementácie funkcie. Naopak, ak nemôžete ani vyjadriť to, čo máte v úmysle napísať, potom implementácia funkcie bude ešte ťažšia. Vaši kolegovia, komentovaním dizajnového dokumentu, vám tiež pomôžu preskúmať vaše myšlienky, nájsť problémy vopred, poukázať na logické chyby a dokonca navrhnúť lepšie metódy implementácie (opakovane som zistil, že kolegovia okolo mňa dôsledne prichádzajú s lepšími riešeniami a identifikujú logické medzery v mojom myslení). First, design documents help you clarify your thoughts. Ak projektový dokument schváli každý, potom každý bude mať viac vlastníctva celého projektu a bude viac ochotný pomôcť zlepšiť kvalitu kódu, čo vedie k vysokej celkovej inžinierskej kvalite pre projekt. Second, design documents help the entire team reach a consensus. Noví členovia tímu a kolegovia z iných tímov môžu ľahko získať vysokú úroveň porozumenia celej kódovej základne prostredníctvom projektových dokumentov.Keď niekto chce pochopiť stav projektu, nie je nič uspokojujúcejšie ako jednoducho odoslať im odkaz. Third, design documents are an excellent supplement to code. V porovnaní s dlhými stretnutiami, návrhové dokumenty umožňujú kolegom (v rôznych časových zónach) pokojne premýšľať nezávisle v ich vlastnom vhodnom čase, zdokonaľovať svoje myšlienky a poskytnúť spätnú väzbu autorovi. Predvývojové diskusie medzi kolegami môžu účinne preskúmať celý návrhový prístup, čo výrazne znižuje riziko chybných návrhov (verte mi, že som bol viac ako raz lenivý a priamo napísal kód, len aby som zistil, že dni môjho vývoja sa ukázali ako zbytočné). Počas vývoja, pretože kolegovia už chápu koncepciu dizajnu, recenzie kódu sa stávajú jednoduchšími. Ak sa problémy vyskytnú počas predvývoja, vývojári môžu tiež ľahšie získať pomoc od kolegov. Po vývoji Fourth, design documents help teams save time. Kolegovia, ktorí sa zúčastňujú na diskusiách, sú často tí, ktorí sa zaujímajú o problém, ktorý projektový dokument má vyriešiť. Prostredníctvom projektových dokumentov môžu rýchlo vytvoriť malé tímy a efektívne dokončiť úlohy s dostatočnou vášňou. Fifth, design documents are excellent for organizing teams. Dizajnové dokumenty často odrážajú inžiniersku gramotnosť autora, jasnosť myslenia pri riešení problémov a schopnosť riešiť dôležité problémy. Sixth, design documents are excellent material for promotion. Keďže písanie projektových dokumentov prináša tímu toľko výhod, prečo nie každý postupuje podľa tejto praxe? "Písanie projektových dokumentov je príliš veľa problémov, možno budem len začať kódovať najprv?" Ak zistíte, že projektové dokumenty je ťažké napísať, naznačuje to, že autor nerozumie problému dostatočne dôkladne a ich zvolená metóda implementácie je pravdepodobne nesprávna. "Ak by som vynechal písanie dokumentu, kód by som už dokončil." Všetko v moderácii. Či je potrebný návrhový dokument závisí od dlhodobej kvality kódu a udržateľnosti projektu. Ak je funkcia ľahko implementovateľná a jej logika je jednoduchá, možno by stačilo jednoduché vytvorenie problému na opísanie funkcie a údržba kódu a zarovnanie tímu možno dosiahnuť prostredníctvom preskúmania kódu. "Som dobrý v tomto, sledujte, ako ho implementujem priamo a zapôsobím na mojich kolegov." Zatiaľ čo mať oblasti odbornosti je plus, komunikácia v rámci tímu je rovnako dôležitá. Na jednej strane, ak kolegovia nerozumejú prístupu autora, je pre nich ťažké vykonávať recenzie kódu; na druhej strane, správca kódu a autor často nie sú rovnakou osobou. Snažte sa tieto vnímania zmeniť, vystúpte zo svojej komfortnej zóny, skúste začať písať dizajnové dokumenty a aktívne sa podieľať na komentovaní iných projektových dokumentov. Anekdota: Raz som sa sťažoval kolegovi: „Naozaj nerozumiem kódu iných ľudí, najmä v jazykoch ako Python, ktoré sú ľahko napísateľné, ale ťažko čitateľné.“ Kolega odpovedal: „Nebojte sa, oni tiež nerozumejú vášmu.“ Potom som sa zasmial a pomyslel si: ak by neboli žiadne dizajnové dokumenty, ktoré by udržiavali každého na vysokej úrovni a každý by komunikoval len čítaním kódu druhého, aké neefektívne by boli operácie tímu?
