Le regole di codifica pulite sono meno rilevanti per i grandi progetti open source? [chiuso]

Per essere chiari, Bob non ha inventato il concetto di codice pulito. Ha appena scritto un libro con quel titolo contenente alcuni consigli molto validi e alcuni consigli e opinioni più dubbi. Scommetto che tutti i manutentori di grandi progetti open source credono nel codice pulito, ma non rispettano necessariamente tutti i principi di quel libro specifico.

Detto questo, penso che tu stia errando sull'opinione di Bob riguardo ai commenti. Bob sostiene la rimozione dei commenti non necessari . I commenti non necessari sono commenti che indicano ciò che è già evidente dal codice, come il classico:

// increment i by one
i++;

O commenti che compensano solo una cattiva variabile / denominazione di funzioni o codice inutilmente contorto.

Ma "spiegazioni linea per linea per il motivo per cui è stato utilizzato un particolare approccio" non è sicuramente superfluo, poiché il codice - per quanto pulito sia scritto - in genere non spiega di per sé perché un certo approccio è usato .

Per esempio, guardando la fonte di Angular.js, trovi due tipi di commenti.

1) Commenti della documentazione API come:

/**
 * @ngdoc function
 * @name angular.isObject
 * @module ng
 * @kind function
 *
 * @description
 * Determines if a reference is an 'Object'. Unlike 'typeof' in JavaScript, 'null's are not
 * considered to be objects. Note that JavaScript arrays are objects.
 *
 * @param {*} value Reference to check.
 * @returns {boolean} True if 'value' is an 'Object' but not 'null'.
 */

2) Commenti di espianto in linea del tipo:

// Need to check if hasOwnProperty exists,
// as on IE8 the result of querySelectorAll is an object without a hasOwnProperty function

Entrambi i tipi di commenti sono assolutamente indicativi di codice pulito e di alta qualità. La documentazione dell'API spiega il funzionamento della libreria per l'utente e i commenti incorporati spiegano perché il codice è scritto così com'è, cioè fornisce informazioni che non sono presenti nel codice stesso.

... people want line by line explanations for why a particular approach was used ...

Riesci a leggere e capire cosa fa il codice? Non hai bisogno di commenti.

Hai capito perché il codice fa quello che fa? Non hai bisogno di commenti.

Altrimenti, i commenti sono probabilmente una buona idea.

Ora: fai avanzare l'orologio "un po 'di tempo" (anni? mesi? settimane, anche?)

Puoi ancora capire cosa fa il codice? Perché lo fa?
È qui che un buon commento si ripaga da solo.

Non ricorderai alcun dato di codice un anno dopo averlo scritto, ma i tuoi commenti dovrebbero aiutarti a tornare a farlo più velocemente.

La parte chiave della sua posizione è cercare, non raggiungere. È una domanda a se vuoi spendere tempo a lucidare nomi e documentazione di variabili o hai funzionato e hai semplicemente spinto il codice. Immagino che la gente preferisca scrivere qualche nuova funzione divertente piuttosto che ripulire il codice morto.

Informazioni sulla fonte specifica che hai collegato. Da una rapida occhiata alla maggior parte dei commenti c'era una documentazione API pubblica che lui chiamava specificatamente buona (pagina 59 della mia copia). Sembra che ce ne siano anche molti che fanno riferimento a modifiche specifiche e rimandano al problema correlato come

//Encode angle brackets to prevent input from being sanitized to empty string #8683

L'esempio deferred.js sembra avere un bel po 'di problemi anche se con codice commentato e un paio di punti in cui sembra che il commento e l'implementazione non corrispondano. Anch'esso ha un numero di commenti che si riferiscono alle specifiche di promesse che sono di valore.

È tutto open source, se pensi di poterlo migliorare, partecipa e invia loro una richiesta di pull. Il prossimo ragazzo ti ringrazierà

Non sempre le grandi aziende obbediscono alle regole, anche se le regole sono a beneficio delle persone.

Situazioni simili risalgono ai tempi in cui Internet Explorer (Microsoft) non seguiva tutte le regole del World Wide Web Consortium. Alcune vecchie versioni di IE hanno alcune implementazioni per JavaScript e CSS che funzionano in modo diverso rispetto alle definizioni W3Consortium, che fanno sì che i progettisti si occupino delle eccezioni basate su browser.

Quindi essere una grande azienda o essere un prodotto di una grande azienda o essere un grande progetto open source non significherebbe che obbedirà agli standard.

Gli standard servono a semplificarci la vita. Lo stesso vale per le regole di clean code , anche se alcune persone trovano alcune regole inutili o inutili. Ma questo non significa che quelle regole siano inutili.

Pensa alle seguenti situazioni:

• Stai lavorando con più di 10 sviluppatori su un progetto. Usi il controllo della versione e ogni sviluppatore deve lavorare su molti file. Devi usare una classe / modulo scritto da 5 diversi sviluppatori. La classe / modulo è uno script abbastanza lungo e devi capire come funziona in modo da poterlo usare correttamente. Preferiresti un merluzzo ben documentato che ti costa meno tempo per capire o un lungo codice con un'appropriata denominazione?
• Nel tuo progetto, hai bisogno di un modulo che faccia un singolo lavoro per te. Hai trovato un progetto open source che è grandioso. Ma sfortunatamente è lungo più di 10.000 righe e devi capire come dovresti usarlo. Ha lunghi nomi di variabili esplicative ma (dato che non sei stato tu a scrivere il codice) non hai docstring. Preferiresti leggere l'intero progetto?
• Hai bisogno di un modulo e ottieni un pacchetto open-source con una grande documentazione sul sito. Quindi inizi a usarlo e qualche settimana dopo boooom! Il progetto open-source ha un bug che influenza la tua situazione. Si apre un ticket ma, sfortunatamente, il progetto non è più supportato e sviluppato o il team è così impegnato da pianificare la correzione dei bug in una data sconosciuta successiva. Si apre il codice sorgente. Ha variabili e funzioni definite con precisione, ma non ha commenti. Quindi non hai idea di dove iniziare la ricerca.

Quindi, avere un nome esplicativo è buono. Anche i commenti sono buoni, ma avere entrambi è meglio . Alcuni grandi progetti potrebbero rifiutarsi di obbedire a clean code rules , ma questo non li rende inutili . Persino Microsoft e altre grandi aziende a volte non obbediscono alle regole e questo ti renderebbe nervoso quando hai bisogno di quelle rules applicate. In quel momento, capisci quanto siano importanti quelle regole.

Commentare è buono - scrivere codice di auto-documentazione è solo meglio. Di solito, i commenti richiedono meno tempo rispetto alla scrittura di un codice di auto-documentazione. Le persone che lavorano su progetti open source, anche alcune di quelle grandi, probabilmente non saranno pagate per questo, e contribuiranno nel loro tempo libero, quindi alcuni di loro potrebbero prendere il modo più semplice, invece di mantenere alti standard come farebbero nella loro lavoro del giorno. A volte è solo pragmatico minimizzare gli sforzi anche a costo di qualità.