Come commentare il codice come un professionista: best practice e buone abitudini

Scrivere codice è molto simile a scrivere prosa. Ogni persona lo fa in modo leggermente diverso e per questo motivo tutti abbiamo una voce distinta quando viene letto il nostro codice. Abbiamo diverse convenzioni di denominazione e diverse logiche di risoluzione dei problemi. Pensiamo tutti che il nostro codice abbia senso, specialmente se funziona, ma qualcun altro potrebbe non farlo. Per combattere questo, dobbiamo migliorare tutti nel commentare il codice sorgente. In questo modo, chiunque si avvicini al progetto avrà un percorso chiaro per comprendere e migliorare/riparare il nostro codice.

Come commentare il codice - Le basi

Per cominciare, assicuriamoci di essere tutti sulla stessa pagina per quanto riguarda i commenti. In questo articolo discuteremo dei commenti in linea all'interno degli script stessi. Cose come queste in un file CSS, ad esempio, dove il codice leggibile è suddiviso da commenti che vengono ignorati dai processori.

/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

Ogni linguaggio di programmazione ha un modo diverso di commentare nel codice sorgente. PHP e HTML e JavaScript e C# hanno tutti simboli leggermente diversi che iniziano e terminano il codice. Sebbene ci siano anche alcune pratiche specifiche per la lingua, sono più condivise che non.

Discuteremo alcuni dei diversi tipi di commenti che incontrerai, i loro usi e le migliori pratiche (o forse solo buone abitudini da prendere) quando li usi tu stesso.

I principi di base per commentare il codice sono semplici:

• Rendili brevi
• Mantienili pertinenti
• Usali liberamente, ma non in eccesso

Se riesci a tenerli a mente, te la caverai abbastanza bene.

Un momento per discutere degli oppositori

Molto brevemente, tocchiamo il codice sorgente commentando gli oppositori. C'è un sottoinsieme non piccolo di sviluppatori che credono che commentare il tuo codice dovrebbe essere un'occasione eccezionalmente rara. Che quando hai bisogno di commenti sul codice sorgente, è un'indicazione che il tuo codice è debole in qualche modo. Che le tue convenzioni di denominazione, la logica o qualcos'altro non siano così trasparenti come dovrebbero essere.

E, per essere onesti, questo argomento ha un certo senso. Tuttavia, esistono una serie di circostanze che costituiscono un argomento più che sufficiente per includere la documentazione sotto forma di commenti, indipendentemente da quanto sia ben scritto e fattorizzato il codice.

I principali sono che non sarai sempre tu a lavorare al progetto e non puoi garantire quanto sarà esperta la prossima persona. Anche se scrivi un ottimo codice, c'è la possibilità di confusione e ambiguità.

Documentazione del blocco di intestazione

Se guardi in alcuni file, il codice non inizia immediatamente perché c'è un'intestazione di grandi dimensioni nel file che descrive qual è il suo scopo, le variabili, le funzioni, i metodi e così via. Potrebbero anche essere in una scatola gigante intorno ad esso per richiamare la tua attenzione.

Questa non è una buona abitudine da prendere. Perché è un po' inutile. Beh, è ​​davvero inutile, in realtà.

Inoltre, guarda l'esempio sopra: l'intestazione del commento è assurdamente lunga. Ci sono molto raramente ragioni per farlo. Quindi non farlo.

Tutto ciò che inseriresti in quel file dovrebbe essere comunque inserito nella tua documentazione. Averlo in un commento è ridondante. Inoltre, l'utente finale probabilmente non entrerà mai nel tuo codice sorgente, quindi il commento verrebbe visto solo da altri sviluppatori (o utenti hardcore del software che già conoscono la documentazione).

Inoltre, ogni volta che la documentazione cambia, devi cambiarla in quel file. È facile perdere un passaggio e quindi la tua base di codice può seriamente rovinarsi.

Quando i commenti dell'intestazione sono utili

I commenti di intestazione sono utili nel codice sorgente per semplici spiegazioni su cosa aspettarsi in quel file. Ad esempio, questo è uno script che viene fornito con un motore di sviluppo del gioco chiamato RPG Maker e il file JS principale che controlla ogni scena di gioco inizia in questo modo:

//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;

Inoltre, tieni presente che il numero di versione è elencato nella parte superiore. Fai questo. Tuttavia, non fornire un elenco completo delle date in cui il file è stato modificato e le nuove versioni pubblicate. Questo è registrato in Git o in un altro software di controllo della versione e dovrebbe essere disponibile per chiunque abbia bisogno di tali informazioni. Il numero di versione è sufficiente per la maggior parte delle persone che guarderanno questo file.

Documentazione in linea

Il tipo più comune di commento del codice sorgente è il commento in linea. C'è una linea sottile con questi tra farlo bene, esagerare o essere troppo parsimoniosi con loro. È un equilibrio che devi imparare nel tempo, ma ci sono alcune buone regole pratiche da considerare.

Non fare commenti riga per riga. Il commento in linea è una cosa. Il commento riga per riga rende il codice quasi illeggibile. Vedi sotto:

function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}

È eccessivo. Se devi, fallo prima o dopo la funzione. Ma non su ogni riga. È invadente e generalmente inutile. Un commento prima della funzione (o elemento) fa bene all'organizzazione e alla chiarezza. Più di questo dovrebbe andare nella documentazione.

Se ritieni che sia necessario documentare, qualcosa del genere sarà sufficiente.

//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}

Gli oppositori menzioneranno che anche questo tipo di commento è ridondante perché buone convenzioni di denominazione per le funzioni, le variabili e i metodi renderanno il codice leggibile. Questo è vero fino a un certo punto, ma se stai cercando di mantenere l'ambiguità al minimo assoluto, un rapido commento è la strada da percorrere.

Va bene inserire avvisi nei commenti del codice sorgente

A volte la soluzione ovvia a un problema non risolve effettivamente il problema. In questi casi, gli sviluppatori che arrivano a un progetto in una fase successiva dello sviluppo possono esaminare un file e considerare il refactoring in quella soluzione ovvia . Farlo sarà una completa perdita di tempo.

O forse in futuro verrà fuori qualcos'altro, e cercano di chiamare una funzione che rompe tutto e mette in ginocchio il progetto.

Indipendentemente da ciò, se hai qualcosa che sai per certo non funzionerà e che sai che altre persone probabilmente proveranno in futuro, va bene avvisarli al riguardo.

// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}

Inoltre, hai notato cosa abbiamo fatto in quell'esempio? Non solo abbiamo dato l'avviso ai futuri sviluppatori, ma abbiamo incluso un commento segnaposto nel mezzo di una funzione. Poiché i commenti del codice sorgente vengono ignorati, puoi usarli per mantenere il testo segnaposto nel file (una specie di annotazione per te stesso per tornare lì, o come esempio per qualcuno come spiegazione).

Non essere un cretino

L'ho già visto accadere prima, specialmente in progetti open source che non sono stati moderati molto bene. Qualcuno troverà uno snippet di codice tutt'altro che stellare e utilizzerà un commento per denigrare l'autore.

//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.

O forse aggiustano il codice, ma includono il codice, semplicemente commentato, in modo che possano mostrare il loro codice, mentre allo stesso tempo si prendono gioco dell'autore precedente.

//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }

Assicurati solo di non farlo mai. Anche se pensi di essere divertente o che ti faccia fare bella figura, non lo è e non è così.

Il vero uso di commentare il codice è di tenerlo a portata di mano mentre provi qualcos'altro. O per fare un esempio di cosa non funzionava prima così qualcuno non ci riprova inutilmente.

Commenti sul codice sorgente per WordPress

In generale, WordPress viene eseguito in quattro lingue diverse. HTML, CSS, PHP e JavaScript. Assicurarsi di utilizzare i caratteri giusti per i commenti è imperativo.

Per HTML:

<!-- comments go here and can be single or on multiple lines --></em>

Nel CSS:

/* Any number of lines will be a comment until the comment is closed */ 

Sia PHP che JavaScript hanno gli stessi metodi per fare commenti su una riga e su più righe:

<?php function(); // a single line comment is like this ?>

o

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

Conclusione

Se sei in trincea giorno dopo giorno, scrivendo codice e spingendo su GitHub, la tua organizzazione potrebbe avere una guida di stile per i commenti che vogliono che tu segua. Se non lo fanno, tuttavia, o sei da solo, tenere a mente queste cose non solo renderà il tuo lavoro più facile in futuro, ma aiuterà anche chiunque ti venga dopo.

Quali sono i tuoi suggerimenti e trucchi per ottenere il massimo dai commenti al tuo codice?

Immagine in primo piano dell'articolo di Skillup / shutterstock.com