È normale / accettabile scrivere note, pensieri, algoritmi, decisioni durante la codifica e la manutenzione? [chiuso]

Non solo è normale, è una buona idea.

C'è una citazione famosa

"Give me six hours to chop down a tree and I will spend the first four sharpening the axe".

Prendersi il tempo necessario per organizzare i propri pensieri e pianificare il proprio lavoro prima che la codifica sia un tempo ben speso. Mettere quei pensieri sulla carta ti darà il tempo di riflettere sui tuoi piani, criticarli e organizzarli in modi che sarebbero molto difficili se fatti solo "nella tua testa".

Sì, è perfettamente accettabile e normale.

La documentazione del processo decisionale è spesso preziosa quando si rivisita il codice, per aiutare a determinare perché il codice è stato scritto in un certo modo.

Queste note possono essere incluse direttamente nel codice come commenti, se abbastanza brevi. Il commento esteso viene spesso mantenuto come parte di un documento di progettazione tecnica esterno.

È una dannata buona idea. Fino a quando non diventa un modo per procrastinare.

La chiave è il saldo. Trovo che io sia più produttivo se non riesco a inscatolare le mie idee ma a catturare le idee man mano che vengono.

Se eseguo una rettifica a un livello basso e viene un'idea di alto livello, annoto e riprendo più tardi.

Pianificare il lavoro è una buona idea, ma a meno che non sia necessario comunicare o presentare al pubblico gli strumenti migliori sono la penna e il tovagliolo. Cattura l'idea. Non perdere tempo a renderlo carino.

In qualsiasi situazione professionale, non è solo "normale e accettabile", è obbligatorio. Il tipico ciclo di sviluppo consiste in due fasi di documentazione prima che inizi anche la codifica:

1. Documento dei requisiti funzionali: generalmente scritto da analisti aziendali, che specifica la funzionalità da implementare.

2. Documento di progettazione del dettaglio: che è più o meno quello di cui stai parlando, solo più formale, specificando la scomposizione funzionale (factoring) del sistema, gli algoritmi, ecc. Alcuni dei miei (molto) quelli vecchi sono online, ad es questo .

Per documentazione meno formale, il 110% concorda con le osservazioni precedenti sui commenti in linea. Questo è il modo solo di andare; in un modo o nell'altro, tutto il resto alla fine si perde. Ma i commenti in linea ordinati e accurati sono un'abilità di codifica separata, sviluppata attraverso lo sforzo e la pratica come qualsiasi altra abilità. Puoi vedere alcune delle mie (molto) vecchie cose in, ad es. questo . Questo stile può o non può piacere a te. Consiglierei innanzitutto di trovare un codice ben commentato con uno stile che ti piace e di emularlo nel tuo codice. Dopo un po ', adattalo come meglio credi.

Un ottimo posto dove inserire questo tipo di informazioni è direttamente nel messaggio di commit del tuo sistema di controllo della versione (SVN, git, ecc.). In questo modo puoi vedere le modifiche e il ragionamento per loro nello stesso posto.

Oltre alle altre buone risposte, aggiungo che spesso scrivo i miei pensieri su ciò che sto cercando di fare.

Essere molto espliciti sull'articolazione di ciò che sto cercando di fare mi aiuta a realizzare presunzioni, ipotesi e / o requisiti che non necessariamente valgono.

Che poi suggerisce alternative, che poi rimugino meglio a turno; quella scrittura aiuta a salvare il mio posto se penso a qualcos'altro.

Prendo note rapide per esplorare respiro e profondità, quindi funziona in modo ricorsivo, aiutandomi a elaborare, navigare e valutare un albero delle soluzioni, eseguendo il backup, esplorando, scoprendo, realizzando e decidendo.

Annotare tutto ciò che può salvarti / (nuovi) membri del team è tempo speso bene. Assicurati che sia qualcosa di cui qualcuno potrebbe aver bisogno in seguito e non pensare troppo a meno che non si tratti di un vero progetto a lungo termine.

Inoltre non dovrebbe richiedere alcun tempo. Se passi il tempo a pensare, puoi scrivere i tuoi pensieri 1 a 1 (a patto che possano / possano essere utili a qualcuno).

Il vero problema potrebbe essere il pensare troppo a quello che scrivi. Solo perché stai scrivendo non significa che devi aderire ad un formato già esistente o che hai bisogno di andare fino in fondo per creare una documentazione completa.

Se la tua scelta è tra non scrivere nulla e solo scrivere note non formali su un blocco note, quindi scrivi solo note non formali.

Dici: "Alcune persone hanno questo problema che non riescono a pensare senza parole e scrivere i loro pensieri e decisioni è il modo più efficace per procedere."

Se scrivere i tuoi pensieri e le tue decisioni è il modo più efficace per procedere, perché non sarebbe normale e accettabile procedere nel modo più efficace? Fai ciò che funziona meglio per te. Potrebbe non essere ciò che funziona meglio per qualcun altro. In tal caso, non lasciare che qualcun altro ti dica cosa è meglio per te e non gli dici che cosa è meglio per loro. Ognuno fa ciò che è meglio per loro.

Gli umani possono tenere in mano solo sette "cose" nella loro testa. Questa è la ragione per i numeri di telefono a sette cifre. Affinché i programmatori possano lavorare in modo efficiente, devono trovare una sorta di sistema per scaricare le cose dalla loro memoria e recuperarle rapidamente in base alle esigenze. Il prendere appunti è un modo ovvio e diretto, ma chiunque lavori su qualcosa di moderatamente complesso deve farlo in qualche modo . Quando accoppi il programma con qualcuno, cerca di individuare il loro metodo.

Un modo comune è lo sviluppo guidato dai test. In questa metodologia, si scrive un test in errore, si scrive solo il codice sufficiente per ottenere il superamento del test, quindi si refactoring il codice per renderlo più bello mantenendo tutti i test esistenti passando. Questa metodologia mantiene tutte le "note" codificate all'interno dei test. Le persone possono lavorare molto rapidamente in questo modo senza sembrare prendere appunti, perché sono focalizzati sul prossimo test.

Un altro modo comune è scrivere semplicemente le note nel codice come commenti o stub pseudocodici, quindi sostituirlo gradualmente con la cosa reale. Questo è il modo in cui solitamente scrivo algoritmi. La mia prima bozza è solo una funzione principale con pseudocodice, quindi gradualmente si espande in livelli sempre più profondi di astrazione.

Non sentirti a disagio nell'usare qualsiasi metodo che funzioni per te, ma cerca di notare quali metodi usano i tuoi colleghi "efficienti". Hanno le stesse limitazioni umane che fai.