Come posso chiedere al mio capo (in modo educato) di commentare il suo codice?

Mi è stato insegnato dal mio capo (ho appena finito la scuola e voleva qualcuno con una piccola esperienza di programmazione, quindi mi ha scelto di addestrarmi su ciò in cui quella società è specializzata) e ha iniziato a lavorare con le applicazioni ASP.NET MVC , alcuni HTML e CSS . Sto bene con le cose di web design che mi dà (è abbastanza semplice da capire senza chiarimenti).

Ma per esempio, mi dà un compito da fare con ASP.NET MVC, lo spiega davvero bene. Ma non spiega nulla nel codice che mi ha appena dato. (Usiamo il controllo del codice sorgente in Visual Studio 2013 ), quindi sono letteralmente centinaia di righe di codice, senza alcun background su ciò che dovrebbe fare. Il tipo di codice che sto vedendo è il codice che non ho mai visto prima, quindi è davvero difficile provare e capire.

Vorrei provare a fargli altre domande, ma lavora sempre (sono affari suoi) e mi sento come se potesse infastidirsi con tutte queste domande che ho tra le mani.

Quindi, solo qualcosa che mi aiuterà fino a quando non avrò un'idea delle cose, come posso chiedere al mio capo di inserire commenti nel suo codice che mi dà, ma educatamente?

Sei nel "profondo" e, secondo me, questo è il modo migliore per imparare. Non perché stai guardando cose di cui non hai idea, ma perché ti costringe a essere più intraprendente e scoprire quali componenti svolgono il ruolo in un sistema in cui sei nuovo.

Non aiuta il fatto che il tuo capo sia troppo occupato per gestire qualcuno che è curioso (e sei totalmente nei tuoi diritti per essere curioso; sei desideroso di imparare, il che è buono). Ma, sfortunatamente, chiedere al tuo senior di cambiare il suo stile e il suo approccio per il bene del tuo apprendimento potrebbe non andare troppo bene, specialmente perché hai a che fare con qualcuno che dici di essere occupato.

Essere seduti davanti a migliaia di righe di codice con cui non si ha familiarità è la norma. Non puoi sempre averlo spiegato in bianco e nero con commenti. Tuttavia, per motivi di apprendimento mentre sei nuovo, se ritieni di dover assolutamente chiedere commenti, forse spiega perché. Spiega che è perché non vuoi disturbarlo con domande poiché è spesso impegnato. Non solo questo si incontrerà molto meno come se gli stessi dicendo di fare qualcosa, ma apre anche la strada alle discussioni su come potrebbe, invece, preferire mettere da parte il tempo per porre domande.

Innanzitutto, strisciare attraverso migliaia di righe di codice sconosciuto e sentirsi persi è come ogni progetto software è, ovunque, dall'inizio dei tempi.

La più grande differenza tra te e un programmatore esperto è che non ci sei abituato.

Alcuni punti da tenere a mente:

1. Con sufficiente sforzo, ogni bit di codice è comprensibile. Molte persone si sentono frustrate se non riescono a capire qualcosa in pochi minuti. Sii più paziente di così.

2. Un buon capo è il più aperto possibile a interruzioni e domande. Un buon impiegato si impegna il più possibile per ridurre al minimo interruzioni e domande. Sii consapevole di ciò.

3. Le interruzioni sono più costose delle domande. Puoi sfruttare meglio il tuo tempo e il tempo del tuo capo consolidando le discussioni e senza mai finire una conversazione confusa.

4. Il tuo capo è un programmatore migliore di te. (Probabilmente.) Questo non vuol dire che non puoi essere più forte in alcune aree, ma nel complesso la sua esperienza è maggiore. Fino a quando non avrai molta esperienza, assicurati di imparare dalle sue competenze il più possibile.

5. Se sei sicuro che più commenti potrebbero aiutare in modo significativo il codice, chiedi al tuo capo. "È difficile per me capire cosa sta succedendo in alcuni luoghi. Quando faccio le cose, ti dispiace se aggiungo commenti?" Forse odia i commenti. Forse lo adorerà. Forse sarà indifferente.

Alla fine, tuttavia, è possibile che tra un paio di mesi ti ricorderai di averlo chiesto e di pensare: "Eh, mi chiedo con cosa ho avuto un problema? Non è poi così male. Hm, beh, non importa."

Se il tuo capo non ha tempo di rispondere a tutte le tue domande, perché pensi che avrà tempo per commentare il suo codice legacy? E inoltre, cosa ti fa pensare che i suoi commenti descriverebbero davvero i pezzi che non capisci per ora? Per la mia esperienza, provare a cambiare lo stile di programmazione dei tuoi capi chiedendogli semplicemente di non funzionare, educato o no.

La cosa migliore che puoi fare in una situazione del genere: commenta le parti del codice che devi capire per fare il tuo lavoro da solo - una volta che avrai compreso quelle parti, ovviamente, e dopo aver ottenuto l'impegno del tuo capo, ciò andrà bene. Se tu o il tuo capo temete di poter interrompere qualcosa aggiungendo commenti, aggiungeteli in un ramo separato e chiedete al vostro capo se si prenderà il tempo di rivedere i vostri commenti prima che si uniscano al tronco. Dato che il tuo capo ha solo un budget limitato, prova a capire cosa fa una determinata parte da solo investendo un ragionevole lasso di tempo. Se rimani davvero bloccato, scrivi la tua domanda in un elenco e chiedi al tuo capo, ad esempio, una volta al giorno invece di disturbarlo ogni 30 minuti. Secondo la mia esperienza, questo approccio funziona con la maggior parte delle persone, anche se sono molto impegnate, purché siano disposte ad aiutarvi, il che è sicuramente il caso della vostra situazione.

In questo modo, sei sicuro di ricevere i commenti di cui hai bisogno e il tuo capo vedrà dove hai bisogno di ulteriori informazioni e se hai le cose giuste. E finché ti limiti a commentare solo le cose non ovvie, ci sono buone probabilità che i tuoi commenti aumentino la qualità complessiva della base di codice, il che potrebbe non solo portare benefici non solo a te, ma anche a tutti coloro che deve fare i conti con il codice, incluso il tuo capo.

Innanzitutto, lascia che questo sia un esempio per commentare correttamente il tuo codice, grasshopper!

Quindi, devo farlo sempre. Ho controllato la mia copia locale e la scrivo e la commento da sola. (Posso rimuoverli di nuovo tutti se ho intenzione di ricontrollare - o lasciarli dentro, se non importa a nessuno.) Quindi quando davvero non riesco a vedere oltre, posso chiedere a qualcuno, qui, penso che lo faccia questo (cosa ho commentato), ho ragione? Quindi potresti aver fatto il commento vero, ma è fatto e questo è il punto.

Questo è più di una semplice richiesta personale. Stai cercando di cambiare abitudini / cultura e non è facile. Non è certamente qualcosa che può essere realizzato con una conversazione in corridoio o un'e-mail. Ci vorrà uno sforzo da parte tua.

Sii il cambiamento che desideri vedere nel mondo.

La citazione può essere erroneamente attribuita al Mahatma Gandhi, ma è un consiglio applicabile. Mentre provi a decifrare la base di codice, scrivi i commenti che vorresti aver visto, al meglio delle tue capacità, e impegnali, dopo essere stato esaminato dal tuo capo. vantaggi:

• Sei proattivo, piuttosto che fastidioso.
• Stai dando il buon esempio. Nel migliore dei casi, il tuo capo / team vedrà i benefici e seguirà l'esempio.
• Alcuni dei commenti probabilmente diranno /* Mystery parameter 3 */o /* 2015-02-09 AidanQuinn: Is this code ever called? */: quelli sono opportunità per i tuoi colleghi per documentare correttamente il codice o correggere bug latenti.
• Se, durante la revisione pre-commit, viene scoperto che un commento che hai scritto non è accurato, i tuoi colleghi ora sanno che il codice non era chiaro.

Astenersi da qualsiasi riscrittura o refactoring mentre si fa questo e l'introduzione di commenti dovrebbe essere quasi priva di rischi. Se riscrivi qualcosa, mantieni tali modifiche come commit separati.

(Prima di intraprendere questo progetto, però, assicurati che le tue aspettative per i commenti siano ragionevoli. Se la tua idea di codice ben commentato è al di fuori della norma ( Esempio 1 , Esempio 2 ), allora ti prenderai solo in giro te stesso.)

Non vorrei chiedere ulteriori commenti, ma ecco alcune idee per te:

1. Pianifica un incontro con il tuo capo e fagli passare il codice ad alto livello. Questo dovrebbe farti cominciare. Mi aspetterei che alcune ore durino forse mezza giornata, così puoi metterti al passo. Ciò dovrebbe includere la progettazione generale, i modelli utilizzati, ecc.
2. Crea un progetto di test e inizia a scrivere test unit sul codice, questo ti aiuterà a capirlo senza influenzarlo. Potresti anche trovare alcuni bug!
3. Eseguire il debug del codice in base alle esigenze per comprendere determinate aree.
4. Elimina un miglioramento o un bug dal backlog e lavoraci su.

I commenti sono OK, ma se il codice è scritto in modo semplice dovrebbe essere comprensibile dopo alcuni giorni.

Inoltre, non aspettarti di capire tutto, è meglio concentrarsi prima sulle aree chiave e quindi espandere la conoscenza della base di codice secondo necessità.

Sono stato in una situazione molto simile alla tua circa un anno fa. Ho iniziato a lavorare con poca esperienza di programmazione (anche se all'inizio conoscevo un po 'di OO e alcune altre lingue) e l'unica persona che mi insegnava aveva pochissimo tempo. È sempre stato utile, ma mi è sembrato di non voler porre ogni singola domanda che avevo.

Altri hanno già suggerito cose estremamente utili qui (scrivere test unitari per esempio, ma per esperienza personale, è qualcosa che sarebbe andato un po '"troppo lontano" per me da zero; o commentare parti del codice da soli, ma ciò potrebbe essere difficile a seconda del primo punto / domanda che ti farò tra un minuto). I seguenti punti riassumono ciò che ho fatto e ciò che mi ha aiutato, ma dipende molto da dove si trovano esattamente i tuoi problemi.

Inoltre, sono d'accordo con @AK_ che ha detto che non hai davvero bisogno di commenti in C #. Questo potrebbe non essere corretto al 100% (penso che ci siano aree in cui i commenti sicuramente aiutano, ad esempio il codice pesante di Reflection) ma in sostanza lo è. Se scrivi davvero "codice pulito" con metodi e variabili ben definiti e hai un sacco di piccoli "morsi" di codice, saranno quasi totalmente inutili. Ogni volta che sentivo il bisogno di commenti durante la lettura del codice finora, poi dopo aver capito cosa faceva, ero molto scontento del modo in cui era stato fatto e pensavo che avrebbe potuto essere molto più chiaro in primo luogo da un buon refactoring. Modifica: sto parlando in particolare dei commenti C # qui, non della documentazione (sia essa documentazione separata o commenti XML), poiché penso che la documentazione sia sempre importante.

• Identifica quali sono esattamente i tuoi problemi e se puoi classificarli. Cioè, hai ancora problemi con il linguaggio stesso o non capisci una sintassi specifica (ad esempio espressioni lambda e LINQ in generale o Riflessione)? Se non capisci le righe di codice, non capirai cosa fa l'intero metodo / blocco, quindi commentarlo da solo sarà difficile. Piuttosto, prendi un buon libro ("C # in breve" è stato per me, ma ho sentito che anche "C # in profondità" è spettacolare) e leggi le cose che incontri. La categorizzazione preventiva di questi problemi rende tutto più semplice, in quanto è possibile colmare contemporaneamente "lacune più grandi" o persino chiedere al proprio capo, poiché non si tratta più di molte domande, ma piuttosto di spiegare un singolo argomento o i costrutti più comunemente utilizzati in modo da poter può ottenere un enorme "impulso"

• Parallelamente a quanto sopra, ho provato a familiarizzare con la "codifica pulita" e le migliori pratiche generali (non specifiche della lingua). L'effetto di questo potrebbe non essere immediato, ma prima o poi ripagherà, sia quando dovrai estendere le cose esistenti o chiederti perché qualcuno abbia creato così tanti piccoli metodi invece di uno in cui tutto è contenuto ;-)

• Ottieni una comprensione dei modelli di progettazione più comuni. Potrebbero apparire qua e là nel codice che stai leggendo, e se li riconosci ti darà immediatamente un momento a-ha. Anche se capisci cosa fa il codice che vedi lì, potrebbe farti domandare perché sia ​​fatto in questo modo, e capirlo da soli spesso non è così facile.

Per favore, non prendere il testo sopra mentre faccio ipotesi sulla tua "abilità", spesso cambio accidentalmente tra parlare delle mie esperienze e parlare "con te". È principalmente inteso come ciò che ho incontrato e ciò che ho fatto . Come altri hanno già detto, questa può essere un'ottima esperienza ed è praticamente lo standard nel lavoro leggere codice che non è tuo e di cui non sai molto in anticipo. Ma può essere davvero soddisfacente capire finalmente cosa sta succedendo lì e riconoscerti migliorando in questa particolare "abilità". Cogli questa opportunità per imparare molto in brevissimo tempo, buona fortuna! :)

Probabilmente non lo farai cambiare stile.

Quello che puoi fare è fare molte domande e scrivere le risposte.

Ho ereditato un'enorme base di codice nel mio ultimo lavoro, poca documentazione e pochi commenti. Quindi proverei per mezz'ora sullo stesso problema, quindi se ancora non riuscissi a capirlo, andrei a chiedere a qualcuno che lo ha scritto o che sapesse come usarlo. Quindi documenterei tutte le cose che mi ha detto. La maggior parte è andata nella nostra documentazione, alcuni sono andati nel codice come commenti. Dopo un anno lì avevo praticamente scritto gran parte della nostra documentazione e sapevo molto della base di codice.

In bocca al lupo!

Avevo lo stesso problema. Sono uno studente di fitologo e ho una buona esperienza di programmazione. Stavo programmando in molte lingue ma niente per l'applicazione premium.

Ho fatto domanda per un lavoro per sviluppatore web e mi hanno immediatamente messo in back-end della programmazione web. Quando il capo mi ha mostrato l'api di base per l'applicazione REST del nodo, pensavo che avrei buttato via. Non ho mai visto funzioni con callback e sintassi così strane. E chiedo al mio capo se ho un problema se non capisco nulla nel codice. Lui triste no, lui triste che ho 1 mese per capirlo e nel frattempo farò un CMS per testarmi con un altro frontender.

Bene, ho fatto 1 riga di codice al momento e ho cercato su Google tutto ciò che non ho saputo. Quindi è passata 1 settimana e conoscevo abbastanza il codice da poter collaborare con il front-end. Il mio codice all'inizio era una schifezza, ma fammi vedere dopo 3 mesi! Sto programmando meglio e più velocemente del nostro architetto software!

Immagino che non smetti mai di imparare! La mia moto -> Continua ad imparare e mantieni la calma :) Non dipendere dal capo, sii indipendente e chiedigli direttamente ma solo i problemi più difficili. Perché sarai felice dopo averlo capito dal tuo stesso ricercatore. E ricorda che quando smetti di imparare qualcosa di sbagliato, impara ogni giorno come essere un buon programmatore.

Se imparerai da capo non andrai mai meglio di lui a impostare il tuo standard, impara a scrivere alla cieca, plug-in VIM o VIM per il tuo IDE, Linux wmii, quindi un giorno andresti oltre il capo ed essere migliore di lui!

Come ingegnere del software di 20 anni, lavorando principalmente su argomenti di sicurezza (SF-PD), dovrei dire che il tuo capo potrebbe non essere la persona che vuoi essere il tuo esempio. La mancanza di commenti è un segno di un programmatore amatoriale autodidatta che non ha mai imparato a fare il lavoro correttamente, o di un ingegnere inesperto. O forse un ingegnere che semplicemente non ha il tempo - scadenze e opportunità possono fare cose orribili al tuo codice! ;) È sicuramente un anti-schema per ogni ingegnere del software competente però.

Il tuo capo potrebbe essere un ottimo programmatore, ma sembra che non sia un buon ingegnere del software. Un ingegnere utilizza l'esperienza di gruppo collettivo per evitare le insidie ​​che altre persone sono già state colte di sorpresa. Commenti efficaci fanno parte dell'esperienza di gruppo collettivo per il software, così come l'analisi delle sollecitazioni fa parte dell'esperienza di gruppo collettivo per l'ingegneria meccanica. Ciò che conta come un commento efficace è però più fluido, ed è sicuramente qualcosa che ottieni dall'esperienza.

La cosa più semplice è che i commenti non dovrebbero dire cosa fa una riga di codice. Ci sono momenti in cui i commenti per dire che anche una funzione è superflua (specialmente in C #). I commenti eccessivi possono essere altrettanto inefficaci (e un indicatore della mancanza di esperienza) perché non è possibile trovare le cose importanti nelle scorie. Come principiante, potresti ancora lavorare per capire "cosa" del codice, e per questo devi solo leggere e capire cosa ha fatto.

La cosa importante per i commenti è che dicono PERCHÉ una riga di codice o una funzione fa quello che fa, dove questo potrebbe non essere ovvio. Devi configurare il modulo X prima del modulo Y? È importante controllare un codice di ritorno per vedere se un file era già aperto o stiamo ignorando consapevolmente il codice di ritorno perché questo è stato controllato da qualche altra parte? Il "perché" del codice sarà rilevante per tutti, indipendentemente dall'esperienza, e lo sarà anche per 6 mesi, quando si sarà dimenticato della buona ragione per fare qualcosa in un modo particolare. Commentare non è solo per altre persone, ma anche per aiutarti in futuro.

Se vuoi evitare di infastidire il tuo capo, fai domande intelligenti. Concentrati sul chiedere il "perché" e cerca di capire tu stesso il "cosa" (a meno che non sia davvero oscuro). A nessun buon capo dispiacerà fare domande se non sono il tipo di cose che potresti aver trovato da R-ing TFM. E a nessun bravo ingegnere dispiacerà che gli venga chiesto di fare qualcosa che renderà la vita di un altro ingegnere significativamente più semplice, a costi ridotti per loro. (Basta non chiedergli di riempire i commenti sull'intera base di codice!;)

Sono stato in una situazione simile, direi

1. Il tuo capo potrebbe desiderare che tu impari in modo sporco (esaminando il codice di cui non hai idea) per un motivo. Questo è il modo in cui apprendiamo di più in un mese di lavoro rispetto a un anno al college, come indicato in altre risposte.

2. Questa è "la norma" come menzionato in altre risposte. Dovresti essere più preoccupato su dove iniziare e su come approcciare e su cosa concentrarti piuttosto che cercare di capire immediatamente ogni linea di codice. Chiedi al tuo capo gli strumenti giusti e i modi per eseguire il debug / scorrere il codice. Questo tipo di domande ti farà guadagnare dei punti.

3. Su base regolare, continua ad avvicinarti al tuo capo per ricevere feedback su come stai facendo, così avrai un'idea di come ti trovi in ​​termini percentuali, supponendo che il tuo capo abbia visto un buon numero di persone nella stessa situazione e abbia un'idea di come hanno fatto.

4. Prendi questo come un'opportunità e man mano che comprendi meglio il codice, continua ad aggiungere commenti che inizialmente ti aspettavi di chiedere al tuo capo.

Se vuoi davvero provare a chiedergli di inserire commenti nel suo codice (non lo consiglio) suggerirei di trovare il codice che devi modificare che potrebbe davvero usare alcuni commenti (la maggior parte è autoesplicativo) e di porre la domanda su come questo "Stavo guardando questo codice qui e sto cercando di capire [Problema che stai riscontrando] e non sono riuscito a trovare alcun commento per aiutarlo a spiegarlo". Fondamentalmente prova a dimostrare che hai fatto uno sforzo per capirlo e spiega perché entrambi potresti trarre vantaggio dalla presenza dei commenti.

Probabilmente il 90% del codice ben scritto non ha bisogno di commenti. Volete davvero solo documentare le parti di codice che sono state ottimizzate e sono diventate piuttosto tese. Una volta ho lavorato presso una società che ti richiedeva di documentare ogni parte di codice che hai modificato sostanzialmente i commenti hanno finito per danneggiare attivamente la leggibilità del codice perché si riferivano spesso a codice che era stato rimosso o modificato oltre il riconoscimento. Attenzione ai commenti scadenti ho trascorso una settimana a eseguire il debug di una funzione e alla fine ho scoperto che il commento che continuavo a leggere sull'impostazione di tale e tale flag su "false" era in realtà l'intero problema che ho impostato la bandiera su "true" e tutto ha funzionato come doveva.

Se vuoi commenti nel codice per capire perché qualcosa è stato scritto, molto probabilmente (considerando che sei nuovo) non capisci ancora le esigenze aziendali. Sono sicuro che conosci tutta la sintassi e puoi leggere il codice, ma a meno che tu non conosca lo scopo di qualche codice, ti sentirai un po 'perso.

Una cosa che mi viene in mente è la programmazione in coppia. Dici che il tuo capo è impressionato dai tuoi progressi, quindi potresti suggerire di lavorare al suo fianco. Questo aiuterà entrambi nel lungo periodo. Il tuo capo si troverà a dover spiegare le cose che dà per scontato e imparerai di più sul business.

Come altri hanno già detto, questo è abbastanza comune, ma ciò non significa che devi solo succhiarlo e scavarlo. Non è necessario comprendere la maggior parte del codice in modo così approfondito come si pensa di fare e ci sono strategie concrete per rendere il "deep end" molto più superficiale:

• Trova qualcosa nel codice relativo all'attività in corso. Di solito il più facile da cercare è qualcosa di visibile all'utente, come l'etichetta del pulsante sulla GUI. Scrivi dove l'hai trovato. Questo sarà il tuo punto di ancoraggio.
• Ora cerca il codice ad un passo e scrivilo. Chi crea il pulsante? Quale codice viene chiamato quando si fa clic sul pulsante?
• Il controllo del codice sorgente è spesso utile per trovare il codice ad un passo. Scopri quando il codice che stai guardando è stato aggiunto o modificato e guarda cos'altro è stato archiviato contemporaneamente e perché.
• Ripeti finché non capisci quanto basta per apportare la modifica, oltre a un livello più profondo per assicurarti di non perdere nulla.
• Se rimani bloccato in qualsiasi momento, ora hai una domanda molto specifica da porre. Ad esempio, "Non riesco a capire da dove viene istanziato questo pulsante."

Ecco i miei $ 0,02 sulla questione. Non sto suggerendo una risposta esclusiva, molto di ciò che è stato detto qui è abbastanza rilevante.

Vorrei provare un po 'di ingegneria sociale per organizzare le cose in modo che il tuo capo trovi più facile / meno dispendioso commentare un po' del suo codice piuttosto che non farlo.

Ora, questo può essere abbastanza facile se eri disposto a correre un grosso rischio e infastidirlo, ma non vogliamo farlo. (nota a margine: potresti non riuscire a fare qualsiasi cosa senza che lui scriva o ti scriva commenti, insisti e lo infastidisca all'infinito ecc.)

Qual è l'alternativa, allora? Alcune idee, a seconda delle circostanze.

opzione 1

1. Prenditi il ​​tempo per capire un pezzo del suo codice come fare X.
2. Ora pensa a un modo ragionevole Y per fraintenderlo .
3. Di 'al capo (via e-mail o a colazione o cosa no) che stai attualmente cercando di capirlo.
4. Aggiungi un commento dicendo che non è chiaro cosa significhi il codice, ma lo capisci come Y; cerca di rendergli visibile questo commento, ma non sforzarti troppo!
5. Agisci assumendo Y - e assicurati che il tuo capo si accorga della tua azione (in modo da non perdere tempo a lavorare a lungo su una falsa ipotesi).
6. Il capo dovrebbe prendere l'iniziativa per correggerti. A questo punto, digli qualcosa del tipo "Vorrei davvero che questo codice avesse un paio di commenti per impedirmi di fare un'ipotesi sbagliata. Correggerò il commento che ho aggiunto da solo. Pensi che potresti aiutarmi con una descrizione generale di questo e quel pezzo di codice? Non ho abbastanza esperienza per capire l'intenzione esatta, e sono solo un paio di frasi farebbe il trucco. " O qualcosa..

opzione 2

Ti stai allenando. Prova a organizzare un incontro settimanale (aggiuntivo?) A frequenza fissa con lui. In questa riunione ripassa un po 'di codice, ma devi essere abbastanza preparato da non dover spiegare ogni singola riga. Ad un certo punto - si spera - si renderà conto che può saltare la riunione se ha appena aggiunto i commenti.

Opzione 3

Fai in modo che un altro collega non riesca a capire lo stesso codice che hai tu. Entrambi affrontate il capo in momenti diversi ponendo le stesse domande. È un modo sicuro per fargli capire che non riesce a fare qualcosa ... ma non tutti hanno il lusso di utili collaboratori nello stesso progetto.

Quindi, solo qualcosa che mi aiuterà fino a quando non avrò un'idea delle cose, come posso chiedere al mio capo di inserire commenti nel suo codice che mi dà, ma educatamente?

Se non riesci a capire il codice, perché pensi che i commenti siano la tua soluzione?

Non conosco il suo stile di programmazione, ma ammetto che se il nome di funzioni e variabili è fuorviante, rende molto difficile la comprensione di un codice. Ma se i nomi e le funzioni o persino l'organizzazione del programma (classi, metodi, proprietà ...) sono tali da rendere comprensibile il codice, allora il codice ti parlerà da solo.

Faresti meglio a chiedergli l'architettura del programma e se vuoi richiederlo per qualcosa, richiedi nomi più significativi per le funzioni; è più conveniente per lui fare.

Anche se c'è un modo per chiederlo educatamente, ci sono due possibilità su cosa il tuo capo penserà dei commenti nel suo codice:

1. O che i commenti nel suo codice sarebbero una buona cosa da avere, oppure

2. Che i commenti nel suo codice non sarebbero una buona cosa.

Se il tuo capo pensa che i commenti nel suo codice non sarebbero una buona cosa da avere (e ci sono ottimi argomenti per questo, vale a dire che il codice dovrebbe essere la documentazione e nessuna documentazione stabilirà mai qualcosa di così preciso e inequivocabile come il codice che lo fa effettivamente ), allora non succederà nulla.

Ora, se per caso il tuo capo pensa che i commenti nel suo codice sarebbero una buona cosa da avere, allora c'è una considerevole possibilità che ti dirà di studiare il suo codice, capire come funziona e procedere ad aggiungere commenti al suo codifica te stesso . (Ci sono molto buoni argomenti anche per questo, cioè è necessario imparare , e il suo tempo è, per definizione, molto più prezioso della tua .)

Quindi, a meno che tu non sia disposto a farlo, potresti fare meglio a non dire nulla.