Scrivi titoli nei commenti in codice? [chiuso]

Stavo sfogliando alcuni vecchi codici che ho scritto (il primo anno all'università) e ho notato che scrivevo titoli di commenti che precedevano varie parti del codice. Cose come queste (provengono da un gioco Monopoli):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Questo potrebbe essere ridondante, e probabilmente inutile se il codice è davvero super chiaro, ma mentre ho scannerizzato il file mi ha sorpreso quanto mi sentissi forte come se sapessi cosa sta succedendo anche se difficilmente ho guardato il codice reale. Posso sicuramente vederlo come appropriato in determinate circostanze, quindi mi chiedo- lo fai? Pensi che sia una buona idea? O è troppo?

Questo è un odore di codice. Questo dice cosa e non perché .

Se questo è necessario, dividere il codice in piccole funzioni.

Lo faccio sempre. Entrambi per contrassegnare cosa sta facendo il codice, e probabilmente ancora più importante, come hai detto, per semplificare la scansione e trovare un blocco di codice. A volte, inoltre, scriverò un processo coinvolto nei commenti e 'riempirò' il codice sotto i commenti mentre procederò.

Trovo interessante quante persone non amano la pratica senza essere in grado di articolare il perché. La ragione per cui commenti del genere sono disapprovati è che sono un segno che hai violato il principio della responsabilità singola. Questo nome specifico viene solitamente utilizzato solo in un contesto OO, ma il concetto generale è anche chiamato coesione e si applica ad altri paradigmi. Le scuole di solito non insegnano questo tipo di principi di progettazione fino alla fine di un corso di laurea, se non del tutto. In effetti, alcuni insegnanti impongono la sua violazione per rendere le cose più facili da classificare stipando tutto in un unico file. Pertanto, l'ignoranza della tua matricola è scusabile, e il fatto che tu abbia notato "qualcosa" di sbagliato e abbia cercato di chiarire con i commenti è persino lodevole in queste circostanze, ma in generale è meglio fissare un progetto poco chiaro piuttosto che provare a coprirlo con dei commenti.

Vedo queste cose come un modo per rendere il codice più chiaro o meno. Se si può dire in base ai metodi nel file quale sia ciascuna parte, non è necessario tuttavia se si devono avere più sezioni, può essere utile. Forse quando un file di codice diventa troppo grande, deve essere suddiviso, il che potrebbe ridurre la necessità di tali commenti.

Direi che se lavori all'interno di un team per elaborare uno standard in modo che tu sia almeno programmando e commentando allo stesso modo in modo da guardare il codice diventa più facile.

Lo faccio perché spesso sto comunicando l'intento con me stesso, o essenzialmente inserendo un comodo segnalibro per cose come "La pulizia dei dati inizia qui". Di solito sotto quel titolo c'è una breve descrizione della logica di ciò che sto facendo e del perché.

Mi piace la ridondanza. Se perdo un quaderno di laboratorio per un motivo o per l'altro, o devo rivisitare il codice che ho scritto anni fa, non mi piace dover mettere insieme quello che stavo facendo e perché lo stavo facendo. Se almeno una parte di quella logica è nel codice, è abbastanza documentato da consentirmi almeno di lavorarci di nuovo.

Penso che parte della mia inclinazione verso di essa sia una buona parte della mia programmazione è di natura statistica e quindi un po 'ripetitiva. Mentre ci potrebbero essere alcuni pezzi di codice in cui ho una funzione utile da cercare, potrei avere diverse dozzine di usi abbastanza simili di qualcosa come una funzione di modello lineare generale. È utile essere in grado di andare a scoprire quale di questi era il "quanto sono sensibili i risultati al codice Choice A vs. Choice B o C" e qual era qualcos'altro. Questo è spesso accelerato dai titoli.

Penso che sia utile in situazioni in cui hai file sorgente giganteschi con dozzine di funzioni e puoi organizzarli liberamente in blocchi del genere. Non sto dicendo che mi piace di più rispetto ai file sorgente più piccoli e più focalizzati ...