A Silicon Valley, si atures a l'atzar un programador al carrer i preguntes: "Abans de començar un projecte, què hauries de fer?" nou de cada deu probablement respondran: "Escriu un document de disseny." a És un arxiu compartit entre els enginyers que descriu una característica que s'ha d'implementar abans d'escriure qualsevol codi. Els documents de disseny sovint consisteixen en múltiples seccions: design document (design doc) Aquest exemple Aquest exemple Resum: Algunes frases simples que descriuen la funció a implementar. Motivació: Per què estem implementant aquesta característica? Preview: Com es veurà la funció després de la seva implementació? Opcions tècniques: Quines opcions tècniques necessitem per implementar aquesta característica? Quins són els pros i els contres de cadascuna? Quina hem triat i per què? Detalls d'implementació necessaris: Llista de plantilles de codi, com provar, com escriure registres, etc. És important assenyalar que un document de disseny ha de romandre d'alt nivell; la implementació específica és la tasca del codi. Un autor principal redacta el document de disseny, i els seus col·legues es comuniquen amb l'autor comentant el document. Tot aquest procés de comunicació sovint dura diversos dies o fins i tot setmanes. Una vegada que l'autor i els col·legues estan d'acord sobre el contingut del document, es pot fusionar a la base de codi. Això també marca l'inici del projecte descrit en el document de disseny. Aquest procés d’incorporar documents de disseny en projectes ofereix nombrosos beneficis. Si pots articular les teves idees en un llenguatge concís i lògicament clar, això indica una profunda comprensió de la implementació de la funció. Al contrari, si no pots ni tan sols expressar el que vols escriure, llavors implementar la funció serà encara més difícil. Els teus col·legues, comentant el teu document de disseny, també t'ajudaran a revisar les teves idees, descobrir problemes amb antelació, assenyalar errors lògics i fins i tot suggerir millors mètodes d'implementació (he trobat repetidament que els col·legues al meu voltant arriben constantment a millors solucions i identifiquen les bretxes lògics en el meu pensament). Programadors especialment experimentats en l'equip poden estalviar-te una quantitat significativa de temps de desenvolupament First, design documents help you clarify your thoughts. Això fa que el pensament tècnic de tothom sigui transparent, i la base de codi esdevingui més mantenible.Si un document de disseny és aprovat per tothom, llavors tothom tindrà més propietat de tot el projecte i estarà més disposat a ajudar a millorar la qualitat del codi, portant a una alta qualitat general d'enginyeria per al projecte. Second, design documents help the entire team reach a consensus. Els nous membres de l'equip i els col·legues d'altres equips poden obtenir fàcilment una comprensió d'alt nivell de tota la base de codi a través dels documents de disseny. Third, design documents are an excellent supplement to code. En comparació amb les reunions llargues, els documents de disseny permeten als col·legues (en diferents zones horàries) reflexionar tranquil·lament de forma independent en el seu moment apropiat, refinar els seus pensaments i proporcionar feedback a l'autor. Les discussions de pre-desenvolupament entre els col·legues poden revisar eficaçment tot l'enfocament del disseny, reduint significativament el risc de dissenys defectuosos (creieu-me, he estat més d'una vegada paràsit i directament va escriure el codi, només per trobar dies del meu desenvolupament van resultar inútils). Durant el desenvolupament, ja que els col·legues ja entenen el concepte de disseny, les revisions del codi es tornen més senzilles. Si sorgeixen problemes durant el pre-desenvolupament, els Fourth, design documents help teams save time. Els col·legues que participen en les discussions són sovint els interessats en el problema que el document de disseny pretén resoldre.A través dels documents de disseny, poden formar ràpidament petits equips i completar tasques eficientment amb suficient passió. Fifth, design documents are excellent for organizing teams. Els documents de disseny sovint reflecteixen l'alfabetització d'enginyeria de l'autor, la claredat del pensament en la resolució de problemes i la capacitat de resoldre problemes importants. Sixth, design documents are excellent material for promotion. Atès que escriure documents de disseny aporta tants beneficis a un equip, per què no tothom segueix aquesta pràctica? "Escriure documents de disseny és massa problema, potser només començaré a codificar primer?" Si trobeu que els documents de disseny són difícils d'escriure, això indica que l'autor no entén prou bé el problema, i el mètode d'implementació triat és probablement incorrecte. "Si deixés d'escriure el document, ja hauria acabat el codi." Tot en moderació. Si es necessita un document de disseny depèn de la qualitat del codi a llarg termini i de la manteniment del projecte. Si una característica és fàcil d'implementar i la seva lògica és senzilla, potser simplement crear un problema per descriure la característica seria suficient, i el manteniment del codi i l'alineació de l'equip es poden aconseguir a través de revisions de codi. "Estic bo en això, mireu-me implementar-ho directament i impressionar els meus col·legues." Mentre que tenir àrees d'experiència és un plus, la comunicació dins de l'equip és igualment important. D'una banda, si els col·legues no entenen l'enfocament de l'autor, és difícil per a ells dur a terme revisions de codi; d'altra banda, el mantenidor de codi i l'autor sovint no són la mateixa persona. Intenta canviar aquestes percepcions, sortir de la teva zona de confort, intentar començar a escriure documents de disseny i participar activament en comentar els documents de disseny d'altres persones. Anècdota: Una vegada em vaig queixar a un col·lega: "Realment no puc entendre el codi d'altres persones, especialment en llenguatges com Python, que són fàcils d'escriure però difícils de llegir."El col·lega va respondre: "No et preocupis, ells tampoc no poden entendre el teu."