Convenzioni del codice: come conserviamo il ritmo veloce di sviluppo di un progetto PHP
Ciao, Habr. Mi chiamo Eugene Udodov, sono il co-fondatore e direttore tecnico di Roistat. Voglio condividere la nostra esperienza nello sviluppo di un prodotto ampio e complesso, il sistema di analisi.
TL; DR : Abbiamo esposto le nostre convenzioni sul codice su github e spiegato nell'articolo come applicarlo nella pratica.
Quando si sviluppano prodotti di grandi dimensioni, c'è un problema comune: nel tempo, un sacco di codice legacy si sta accumulando, le attività stanno diventando sempre più lente. Inoltre, con la crescita del team, gli sviluppatori iniziano a scrivere il codice in modi diversi e la mancanza di regole uniformi può portare a conflitti e controversie.
Per 4 anni di esistenza del nostro progetto abbiamo fatto più di 20 000 Pull Request'ov (ulteriori PR) e sotto katom dirò, come abbiamo risolto questi problemi.
Ho provato a scrivere l'articolo più utile. Sarà interessante per te se hai riscontrato i seguenti problemi.
Se sei un direttore tecnico o tecnico:
Devi dedicare molto tempo a capire cosa sta succedendo in un codice di progetto non familiare
Per ogni attività, devi dire agli sviluppatori gli stessi errori
Dopo aver discusso su come eseguire la funzione, lo sviluppatore fa che il PR non sia come concordato
Dopo una PR errata, lo sviluppatore, correggendo alcuni errori, ne fa altri
Trascorri molto tempo ad apprendere ogni nuovo sviluppatore, anche se non rimane a lungo in seguito
Gli sviluppatori senior escogitano le proprie regole e le impongono ai ragazzi meno esperti
Se sei un product manager:
Quando si discute di ciascuna (sembra non essere la più difficile) le caratteristiche degli sviluppatori ti dicono che è lungo e costoso farlo
Capisci approssimativamente i principi della programmazione, ma nel codice del tuo progetto non capisci nulla
Devi aspettare molto tempo prima che i nuovi sviluppatori possano accedere al corso prima di poter eseguire compiti complessi
L'inizio
All'inizio del 2014 in Roistat lavoravano solo 2-3 sviluppatori, ma i primi problemi iniziarono anche allora. Siamo di fronte al fatto che ogni sviluppatore ha bisogno di spiegare gli stessi errori. E con il crescente numero di sviluppatori, questa situazione è solo peggiorata.
Anche con sviluppatori esperti, è sorto un altro problema. Ognuno di loro aveva la propria esperienza accumulata e la sua comprensione di come costruire l'architettura del progetto. Molto spesso le loro opinioni si contraddicevano a vicenda.
Problemi simili accumulati come una palla di neve. Era chiaro che se questo continua, lo sviluppo perderà velocità, flessibilità e ogni rilascio sarà dato attraverso il dolore.
Ricerche di soluzioni
Per prima cosa abbiamo discusso le aree problematiche e concordato le parole su come agiremo in questi casi in futuro. Naturalmente, non ha funzionato. Dopo un po ', tutti avevano un'idea diversa di quello che avevamo concordato prima. Inoltre, i nuovi sviluppatori non erano a conoscenza di questi accordi.
Poi abbiamo pensato: "Come puoi registrare queste informazioni per tutti nella stessa forma?". Abbiamo provato a registrare video di formazione in cui abbiamo parlato dell'architettura del progetto e dei principi di base del nostro sviluppo. Ma questo formato era molto scomodo. Il video è difficile da correggere o riscrivere. Durante la crescita attiva del progetto, sorgono costantemente nuove situazioni e nuovi problemi, che richiedono nuovi accordi o cambiamenti nei vecchi.
Quindi abbiamo iniziato a registrare i risultati delle nostre discussioni in un documento separato. All'inizio erano solo poche frasi. Ma abbiamo concordato che gli sviluppatori di Code Review non dovrebbero imporre la loro opinione personale sul codice. Invece, devono fare riferimento a questo documento e sottolineare le incongruenze con esso. Se non ha la regola giusta, prima dobbiamo discutere il problema, elaborare insieme una soluzione, scriverla in un documento e poi tornare indietro e continuare la revisione del codice.
E ha funzionato. I problemi con diverse comprensioni degli accordi iniziarono a ridursi al minimo. Nel documento, abbiamo scritto spiegazioni dettagliate con esempi di codice in modo che nessuno potesse interpretarle in modi diversi. Ogni nuovo sviluppatore del nostro team potrebbe immediatamente capire cosa gli viene richiesto e come dovremmo fare in diverse situazioni. La revisione del codice, invece di discussioni e dispute senza fine, è diventata un processo abbastanza trasparente e pragmatico.
Dopo sei mesi di lavoro, questo documento conteneva già molte informazioni utili e divenne uno strumento indispensabile nel lavoro del team. L'abbiamo chiamato Convenzioni sul codice (o Code Conv).
Convenzioni sul codice
Code Conv sono regole che devi seguire quando scrivi il codice. Distinguiamo tra Code Style e Code Conv. Per noi, lo stile del codice è l'aspetto del codice. Cioè, la disposizione di rientri, virgole, parentesi e altro. Un codice Conv è il contenuto semantico del codice. Algoritmi di azione corretti, corretti nel senso del nome di variabili e metodi, la corretta composizione del codice. La conformità con lo stile del codice è facilmente verificabile automaticamente. Ma per verificare la conformità Code Conv nella maggior parte dei casi, solo una persona può.
Aderiamo al seguente approccio quando utilizziamo Code Conv.
Per lo sviluppatore:
Lo sviluppatore sta studiando questo documento prima di scrivere la prima riga di codice nel nostro team.
Lo sviluppatore deve comprendere e comprendere le regole scritte. Basta imparare questo documento non funziona.
Lo sviluppatore osserva rigorosamente le regole di Code Conv durante la scrittura del codice.
Lo sviluppatore crea un PR, lo esamina immediatamente e verifica la conformità con Code Conv
Lo sviluppatore invia PR alla revisione del codice e corregge gli errori e le incoerenze di Code Conv ai quali puntano e che si è perso
Per il revisore del codice:
Il revisore verifica la conformità del codice alle regole descritte in Codice Conv
Se un commento appare allo sviluppatore durante la revisione del codice, deve essere accompagnato da un riferimento a Code Conv.
Se Code Conv non ha l'elemento richiesto, il gruppo di lavoro sta per creare una nuova regola e correggerla nel documento. Successivamente, il revisore torna al controllo PR
Pochi esempi
Per chiarire di cosa sto parlando, ecco alcuni esempi di come questo documento appare nella realtà.
All'inizio del documento c'è un sommario. Nel tempo, le informazioni diventano più e senza un sommario - ovunque.
Abbiamo 3 sezioni principali: valori, principi generali e regole specifiche.
I valori sono requisiti aziendali per un team di sviluppo. Le imprese non conoscono nel dettaglio quali metodologie e principi vengono utilizzati internamente, ma è importante che il prodotto sia sviluppato in modo semplice, rapido e che con il tempo non si complichi. Questi valori dovrebbero essere seguiti dall'intero team nello sviluppo di nuove regole e nella risoluzione di problemi che non sono descritti nelle regole.
I principi sono modi di osservare i valori descritti in precedenza. Sono un po 'più dettagliati, contengono le principali metodologie di sviluppo e gli approcci che seguiamo. Uno sviluppatore esperto non deve ricordare a memoria l'intero documento. È sufficiente per lui comprendere questi principi e può dedurre da solo tutte le altre regole da questi principi in qualsiasi momento.
Tuttavia, valori e principi possono essere interpretati in modi diversi. Per evitare fraintendimenti, il documento contiene regole specifiche e esempi di codice che mostrano come è possibile farlo e come è possibile.
Ci sono molte di queste regole ed è loro che costituiscono la maggior parte del documento. Grazie a loro, l'ordine è rispettato.
In pratica, l'applicazione del documento è la seguente.
Uno sviluppatore di codice che lascia commenti su sezioni di codice in cui ha notato una non conformità con Code Conv. Nel commento indica quale regola è violata. E facoltativamente, se non è ovvio, aggiunge una spiegazione perché la pensa così.
Ad esempio, in questo screenshot vediamo che il principio di DRY (Do not Repeat Yourself) viene violato. Nonostante il fatto che in questo particolare PR lo sviluppatore abbia scritto il codice senza ripetizioni e sia sembrato usarlo solo una volta, ha comunque creato un metodo che non può essere utilizzato in futuro senza ulteriori verifiche. Cioè, ha creato un metodo che ovviamente richiede una ripetizione del codice e della logica.
Obiezioni frequenti da parte degli sviluppatori
Gli sviluppatori spesso cercano di far passare attraverso vari pretesti il loro codice che non è conforme a Code Conv. Trovano una varietà di scuse per le loro violazioni, ma ce ne sono alcune delle più frequenti.
"Ma una volta puoi?"
Gli sviluppatori pensano che una singola violazione di Code Conv non porterà alcun danno. Inoltre a volte pensano che in qualche posto non molto importante queste regole non diano valore o non siano critiche. In risposta, ci riferiamo sempre alla teoria delle finestre rotte : "Se un vetro è rotto nell'edificio e nessuno lo sostituisce, dopo un po 'non ci sarà più un'intera finestra in questo edificio". Se facciamo eccezioni alle regole, allora in mezzo anno ci troveremo in una situazione in cui tutto il codice del progetto consiste in violazioni simili.
"Ma ne hai bisogno urgentemente!"
Gli sviluppatori spesso affermano che sarà normale farlo per un lungo periodo e che il cliente è in attesa della soluzione del problema ed è necessario disporre il montaggio il più rapidamente possibile. Ma, in primo luogo, Code Conv non vieta di eseguire la prima iterazione con un codice semplificato. Semplicemente, questo codice deve comunque soddisfare gli standard di qualità. In secondo luogo, se hai ancora bisogno di rompere Code Conv, allora è permesso farlo se l'entropia creata non è maligna (vedi sotto). Ma anche in questo caso, tutti dovrebbero avere una comprensione comune che seguire CodeConv in questa situazione costerà molto di più.
Alcune parole sull'entropia. Entropia è la quantità di informazioni che un progetto consiste (la capacità di informazione di un progetto). Se lo sviluppatore scrive codice che aggiunge informazioni critiche, che ogni sviluppatore deve conoscere, allora tale entropia è maligna. Spesso un tale codice è una mina a effetto ritardato. Cioè, al momento questa ignoranza non può influenzare nulla, e in futuro a causa di ciò, si possono commettere errori critici. Chiamiamo questa entropia maligna. Se l'ignoranza delle informazioni non influisce sul lavoro di altri sviluppatori, allora tale entropia non nuoce e la chiamiamo benigna.
Ad esempio, se creiamo un microservizio separato, che ascolterà alcuni eventi e aggiungerà statistiche da qualche parte, questo servizio non introduce entropia maligna. Se altri sviluppatori non conoscono questo servizio, non commetteranno errori, non influenzeranno il loro lavoro. Se si rompe, quindi oltre al proprietario di questo servizio, nessuno ne soffrirà. Quindi per tale servizio è possibile effettuare la prima iterazione (come Proof of Concept) con una bassa qualità del codice. E poi, se ha bisogno di essere sviluppato, sarà necessario correggere il debito tecnico che è stato messo e lavorare con esso secondo tutte le regole. Alla fine, Code Conv non proibisce la sperimentazione e crea concetti facili e veloci, se non influisce sul resto del sistema.
conclusione
Questo approccio ci ha permesso per oltre quattro anni di mantenere un alto tasso di sviluppo, è facile introdurre nuovi sviluppatori e non rallentare nel tempo.
Tra gli aspetti negativi, si può notare che con questo approccio, Code Review richiede più tempo del solito. Anche piccoli problemi possono essere ritardati per diversi giorni o più a causa degli errori non più importanti.
Ma questo meno viene bloccato da vantaggi, dal momento che il codice dannoso non entra nella battaglia e tutte le "finestre" rimangono intatte.
Ci è stato ripetutamente chiesto di condividere un esempio di Code Conv.
Abbiamo deciso di condividerlo con tutti e renderlo pubblico. Puoi prenderlo così com'è e usarlo subito. Oppure puoi cambiare per te stesso. Inoltre siamo aperti a PR e consideriamo i vostri suggerimenti per il miglioramento.
Link al nostro codice Conv
Stiamo attivamente espandendo il team di sviluppo, quindi se sei vicino al nostro approccio, rispondi alla nostra offerta di lavoro o scrivi per posta .
TL; DR : Abbiamo esposto le nostre convenzioni sul codice su github e spiegato nell'articolo come applicarlo nella pratica.
Quando si sviluppano prodotti di grandi dimensioni, c'è un problema comune: nel tempo, un sacco di codice legacy si sta accumulando, le attività stanno diventando sempre più lente. Inoltre, con la crescita del team, gli sviluppatori iniziano a scrivere il codice in modi diversi e la mancanza di regole uniformi può portare a conflitti e controversie.
Per 4 anni di esistenza del nostro progetto abbiamo fatto più di 20 000 Pull Request'ov (ulteriori PR) e sotto katom dirò, come abbiamo risolto questi problemi.
Ho provato a scrivere l'articolo più utile. Sarà interessante per te se hai riscontrato i seguenti problemi.
Se sei un direttore tecnico o tecnico:
Devi dedicare molto tempo a capire cosa sta succedendo in un codice di progetto non familiare
Per ogni attività, devi dire agli sviluppatori gli stessi errori
Dopo aver discusso su come eseguire la funzione, lo sviluppatore fa che il PR non sia come concordato
Dopo una PR errata, lo sviluppatore, correggendo alcuni errori, ne fa altri
Trascorri molto tempo ad apprendere ogni nuovo sviluppatore, anche se non rimane a lungo in seguito
Gli sviluppatori senior escogitano le proprie regole e le impongono ai ragazzi meno esperti
Se sei un product manager:
Quando si discute di ciascuna (sembra non essere la più difficile) le caratteristiche degli sviluppatori ti dicono che è lungo e costoso farlo
Capisci approssimativamente i principi della programmazione, ma nel codice del tuo progetto non capisci nulla
Devi aspettare molto tempo prima che i nuovi sviluppatori possano accedere al corso prima di poter eseguire compiti complessi
L'inizio
All'inizio del 2014 in Roistat lavoravano solo 2-3 sviluppatori, ma i primi problemi iniziarono anche allora. Siamo di fronte al fatto che ogni sviluppatore ha bisogno di spiegare gli stessi errori. E con il crescente numero di sviluppatori, questa situazione è solo peggiorata.
Anche con sviluppatori esperti, è sorto un altro problema. Ognuno di loro aveva la propria esperienza accumulata e la sua comprensione di come costruire l'architettura del progetto. Molto spesso le loro opinioni si contraddicevano a vicenda.
Problemi simili accumulati come una palla di neve. Era chiaro che se questo continua, lo sviluppo perderà velocità, flessibilità e ogni rilascio sarà dato attraverso il dolore.
Ricerche di soluzioni
Per prima cosa abbiamo discusso le aree problematiche e concordato le parole su come agiremo in questi casi in futuro. Naturalmente, non ha funzionato. Dopo un po ', tutti avevano un'idea diversa di quello che avevamo concordato prima. Inoltre, i nuovi sviluppatori non erano a conoscenza di questi accordi.
Poi abbiamo pensato: "Come puoi registrare queste informazioni per tutti nella stessa forma?". Abbiamo provato a registrare video di formazione in cui abbiamo parlato dell'architettura del progetto e dei principi di base del nostro sviluppo. Ma questo formato era molto scomodo. Il video è difficile da correggere o riscrivere. Durante la crescita attiva del progetto, sorgono costantemente nuove situazioni e nuovi problemi, che richiedono nuovi accordi o cambiamenti nei vecchi.
Quindi abbiamo iniziato a registrare i risultati delle nostre discussioni in un documento separato. All'inizio erano solo poche frasi. Ma abbiamo concordato che gli sviluppatori di Code Review non dovrebbero imporre la loro opinione personale sul codice. Invece, devono fare riferimento a questo documento e sottolineare le incongruenze con esso. Se non ha la regola giusta, prima dobbiamo discutere il problema, elaborare insieme una soluzione, scriverla in un documento e poi tornare indietro e continuare la revisione del codice.
E ha funzionato. I problemi con diverse comprensioni degli accordi iniziarono a ridursi al minimo. Nel documento, abbiamo scritto spiegazioni dettagliate con esempi di codice in modo che nessuno potesse interpretarle in modi diversi. Ogni nuovo sviluppatore del nostro team potrebbe immediatamente capire cosa gli viene richiesto e come dovremmo fare in diverse situazioni. La revisione del codice, invece di discussioni e dispute senza fine, è diventata un processo abbastanza trasparente e pragmatico.
Dopo sei mesi di lavoro, questo documento conteneva già molte informazioni utili e divenne uno strumento indispensabile nel lavoro del team. L'abbiamo chiamato Convenzioni sul codice (o Code Conv).
Convenzioni sul codice
Code Conv sono regole che devi seguire quando scrivi il codice. Distinguiamo tra Code Style e Code Conv. Per noi, lo stile del codice è l'aspetto del codice. Cioè, la disposizione di rientri, virgole, parentesi e altro. Un codice Conv è il contenuto semantico del codice. Algoritmi di azione corretti, corretti nel senso del nome di variabili e metodi, la corretta composizione del codice. La conformità con lo stile del codice è facilmente verificabile automaticamente. Ma per verificare la conformità Code Conv nella maggior parte dei casi, solo una persona può.
Aderiamo al seguente approccio quando utilizziamo Code Conv.
Per lo sviluppatore:
Lo sviluppatore sta studiando questo documento prima di scrivere la prima riga di codice nel nostro team.
Lo sviluppatore deve comprendere e comprendere le regole scritte. Basta imparare questo documento non funziona.
Lo sviluppatore osserva rigorosamente le regole di Code Conv durante la scrittura del codice.
Lo sviluppatore crea un PR, lo esamina immediatamente e verifica la conformità con Code Conv
Lo sviluppatore invia PR alla revisione del codice e corregge gli errori e le incoerenze di Code Conv ai quali puntano e che si è perso
Per il revisore del codice:
Il revisore verifica la conformità del codice alle regole descritte in Codice Conv
Se un commento appare allo sviluppatore durante la revisione del codice, deve essere accompagnato da un riferimento a Code Conv.
Se Code Conv non ha l'elemento richiesto, il gruppo di lavoro sta per creare una nuova regola e correggerla nel documento. Successivamente, il revisore torna al controllo PR
Pochi esempi
Per chiarire di cosa sto parlando, ecco alcuni esempi di come questo documento appare nella realtà.
All'inizio del documento c'è un sommario. Nel tempo, le informazioni diventano più e senza un sommario - ovunque.
Abbiamo 3 sezioni principali: valori, principi generali e regole specifiche.
I valori sono requisiti aziendali per un team di sviluppo. Le imprese non conoscono nel dettaglio quali metodologie e principi vengono utilizzati internamente, ma è importante che il prodotto sia sviluppato in modo semplice, rapido e che con il tempo non si complichi. Questi valori dovrebbero essere seguiti dall'intero team nello sviluppo di nuove regole e nella risoluzione di problemi che non sono descritti nelle regole.
I principi sono modi di osservare i valori descritti in precedenza. Sono un po 'più dettagliati, contengono le principali metodologie di sviluppo e gli approcci che seguiamo. Uno sviluppatore esperto non deve ricordare a memoria l'intero documento. È sufficiente per lui comprendere questi principi e può dedurre da solo tutte le altre regole da questi principi in qualsiasi momento.
Tuttavia, valori e principi possono essere interpretati in modi diversi. Per evitare fraintendimenti, il documento contiene regole specifiche e esempi di codice che mostrano come è possibile farlo e come è possibile.
Ci sono molte di queste regole ed è loro che costituiscono la maggior parte del documento. Grazie a loro, l'ordine è rispettato.
In pratica, l'applicazione del documento è la seguente.
Uno sviluppatore di codice che lascia commenti su sezioni di codice in cui ha notato una non conformità con Code Conv. Nel commento indica quale regola è violata. E facoltativamente, se non è ovvio, aggiunge una spiegazione perché la pensa così.
Ad esempio, in questo screenshot vediamo che il principio di DRY (Do not Repeat Yourself) viene violato. Nonostante il fatto che in questo particolare PR lo sviluppatore abbia scritto il codice senza ripetizioni e sia sembrato usarlo solo una volta, ha comunque creato un metodo che non può essere utilizzato in futuro senza ulteriori verifiche. Cioè, ha creato un metodo che ovviamente richiede una ripetizione del codice e della logica.
Obiezioni frequenti da parte degli sviluppatori
Gli sviluppatori spesso cercano di far passare attraverso vari pretesti il loro codice che non è conforme a Code Conv. Trovano una varietà di scuse per le loro violazioni, ma ce ne sono alcune delle più frequenti.
"Ma una volta puoi?"
Gli sviluppatori pensano che una singola violazione di Code Conv non porterà alcun danno. Inoltre a volte pensano che in qualche posto non molto importante queste regole non diano valore o non siano critiche. In risposta, ci riferiamo sempre alla teoria delle finestre rotte : "Se un vetro è rotto nell'edificio e nessuno lo sostituisce, dopo un po 'non ci sarà più un'intera finestra in questo edificio". Se facciamo eccezioni alle regole, allora in mezzo anno ci troveremo in una situazione in cui tutto il codice del progetto consiste in violazioni simili.
"Ma ne hai bisogno urgentemente!"
Gli sviluppatori spesso affermano che sarà normale farlo per un lungo periodo e che il cliente è in attesa della soluzione del problema ed è necessario disporre il montaggio il più rapidamente possibile. Ma, in primo luogo, Code Conv non vieta di eseguire la prima iterazione con un codice semplificato. Semplicemente, questo codice deve comunque soddisfare gli standard di qualità. In secondo luogo, se hai ancora bisogno di rompere Code Conv, allora è permesso farlo se l'entropia creata non è maligna (vedi sotto). Ma anche in questo caso, tutti dovrebbero avere una comprensione comune che seguire CodeConv in questa situazione costerà molto di più.
Alcune parole sull'entropia. Entropia è la quantità di informazioni che un progetto consiste (la capacità di informazione di un progetto). Se lo sviluppatore scrive codice che aggiunge informazioni critiche, che ogni sviluppatore deve conoscere, allora tale entropia è maligna. Spesso un tale codice è una mina a effetto ritardato. Cioè, al momento questa ignoranza non può influenzare nulla, e in futuro a causa di ciò, si possono commettere errori critici. Chiamiamo questa entropia maligna. Se l'ignoranza delle informazioni non influisce sul lavoro di altri sviluppatori, allora tale entropia non nuoce e la chiamiamo benigna.
Ad esempio, se creiamo un microservizio separato, che ascolterà alcuni eventi e aggiungerà statistiche da qualche parte, questo servizio non introduce entropia maligna. Se altri sviluppatori non conoscono questo servizio, non commetteranno errori, non influenzeranno il loro lavoro. Se si rompe, quindi oltre al proprietario di questo servizio, nessuno ne soffrirà. Quindi per tale servizio è possibile effettuare la prima iterazione (come Proof of Concept) con una bassa qualità del codice. E poi, se ha bisogno di essere sviluppato, sarà necessario correggere il debito tecnico che è stato messo e lavorare con esso secondo tutte le regole. Alla fine, Code Conv non proibisce la sperimentazione e crea concetti facili e veloci, se non influisce sul resto del sistema.
conclusione
Questo approccio ci ha permesso per oltre quattro anni di mantenere un alto tasso di sviluppo, è facile introdurre nuovi sviluppatori e non rallentare nel tempo.
Tra gli aspetti negativi, si può notare che con questo approccio, Code Review richiede più tempo del solito. Anche piccoli problemi possono essere ritardati per diversi giorni o più a causa degli errori non più importanti.
Ma questo meno viene bloccato da vantaggi, dal momento che il codice dannoso non entra nella battaglia e tutte le "finestre" rimangono intatte.
Ci è stato ripetutamente chiesto di condividere un esempio di Code Conv.
Abbiamo deciso di condividerlo con tutti e renderlo pubblico. Puoi prenderlo così com'è e usarlo subito. Oppure puoi cambiare per te stesso. Inoltre siamo aperti a PR e consideriamo i vostri suggerimenti per il miglioramento.
Link al nostro codice Conv
Stiamo attivamente espandendo il team di sviluppo, quindi se sei vicino al nostro approccio, rispondi alla nostra offerta di lavoro o scrivi per posta .
Коментарі
Дописати коментар