Il mio capo vuole una spiegazione inglese narrativa riga per riga del nostro codice

Mi è stato specificamente chiesto di fornire spiegazioni riga per riga (o, se del caso, ad esempio immagine per immagine, ecc.) Che il mio capo vuole essere in grado di leggere e seguire.

Dal momento che non è un programmatore, non può seguire il codice, quindi vuole che tutto sia tradotto in inglese.

Qualcuno è stato invitato a farlo prima?

Ho commentato tutto il codice sorgente e ho usato JSDoc per generare la documentazione completa di tutte le funzioni, variabili, ecc ... e ho incluso un esempio di implementazione e dimostrazioni complete di lavoro con commenti in tutto.

C'è qualcos'altro che posso fare per commentare il codice per i non programmatori?

Questa non è una richiesta ragionevole, vero?

AGGIORNARE

Alla fine, sono riuscito a spiegare perché non è stato un buon uso del tempo per fare ciò che stava chiedendo. È un ragazzo ragionevole e non capiva cosa comporta il mio lavoro. Una volta che ha visto questo post, penso che abbia capito rapidamente che non era una richiesta normale.

Ho fornito la documentazione adatta a un altro programmatore da seguire (JSDoc e commenti in linea - nonché alcune note aggiuntive su problemi tecnici) e un diagramma di diagramma di flusso molto ampio della logica principale del programma che il mio capo deve seguire.

Alla fine, tutte le parti erano soddisfatte e siamo passati avanti.

No , non è una richiesta ragionevole!

PARLAMI FUORI DI ESSO , o chiedi a qualcun altro di discuterne, con ogni mezzo. Questa è un'idea irrazionale, che sebbene fattibile sia così costosa da fare, non dovrebbe mai essere effettivamente realizzata. Una panoramica di funzioni e subroutine è ragionevole, ma per "spiegare" non lo è ogni riga di codice. Sarebbe più efficace per lui imparare a leggere la lingua in mano, piuttosto che farlo.

La prossima cosa che chiederà è tradurre formule matematiche o quant'altro in testo inglese. Anche se certamente possibile, ciò introduce molto spazio per errori e interpretazioni errate e non dovrebbe mai essere fatto. Proprio come "tradurre" il codice in inglese.

Hai documenti di progettazione ? Quella è la spiegazione inglese di ciò che fa il codice. Un manager non programmatore non dovrebbe aver bisogno di altro.

Esiste un premio di micro-manager dell'anno? Sembra che il tuo capo meriti una nomination. Qualcuno che crede di aver bisogno della comprensione del codice riga per riga, ma non vuole imparare a leggerlo direttamente, è perfetto come un micro-manager come si può immaginare.

Uno dei vantaggi di essere uno sviluppatore è che la difficoltà di comprendere il codice impedisce la micromanagement oltre un certo grado, almeno a livello di implementazione dettagliata, almeno da parte di una gestione non tecnica, perché anche il micro-manager più rigido riconosce che sono sopra la loro testa a quel livello. Ma il genio del tuo capo potrebbe trovare un modo per distruggere la cortina di silicone.

E, come bonus, spreca enormi quantità di tempo per gli sviluppatori nel fare la traduzione, anche prima che usi la traduzione inglese per iniziare a suggerire vari miglioramenti (suppongo che sappia come programmare meglio dei programmatori, anche se non può leggi il codice e sarà in grado di condividere la sua saggezza non appena qualcuno lo tradurrà, altrimenti perché dovrebbe aver bisogno di tradurre ogni riga?).

Quindi no, non è una richiesta ragionevole e non ne ho mai sentito parlare prima. E io provo per te. Penso che tutti potrebbero aver bisogno di iniziare tranquillamente a cercare un altro lavoro, perché una volta che inizia a utilizzare la traduzione del codice come strumento di gestione, sarà probabilmente un luogo brutale in cui lavorare (ehm, un luogo più brutale in cui lavorare).

Tra i lati positivi, forse puoi ottenere un nuovo anti-pattern che prende il nome dalla tua situazione? Che ne dici dell'anti-pattern "Dirty Hungarian Phrasebook", dopo la scenetta di Monty Python in cui un tabaccaio sta cercando di comunicare con qualcuno che non parla inglese usando un frasario ungherese che ha traduzioni comicamente false?

Siediti con lui e parlagli attraverso 10 righe del codice. Spiega ogni dettaglio fino a quando entrambi concordano che capisce nella misura in cui voleva.

Forse questa esperienza è tutto ciò che sta cercando: solo un'impressione di come il tuo lavoro ti assomiglia e di come si presenta il software dal tuo punto di vista. Questa è una buona cosa nel mio libro.

Se dopo questo, vuole ancora che tu continui, dì: nota quante domande ho dovuto porre; immagina se avrei dovuto spiegare tutto ciò senza essere in grado di porre domande, come avrei potuto sapere cosa includere e cosa escludere? Quanto tempo ci sarebbe voluto prima che i risultati ti fossero utili? Ora quante righe vuoi che io faccia in questo modo?

Non penso sia una richiesta ragionevole. Il CODICE SORGENTE non deve essere letto in inglese (o in qualsiasi altra lingua).

Forse ha paura che farai in modo che il tuo codice faccia qualcosa che non approva o di cui è a conoscenza. In tal caso, non credo che ci sia qualcosa che puoi fare al riguardo. Dovrai scrivere la documentazione o magari convincerlo a assumere qualcuno per controllare il tuo codice.

È davvero molto semplice:

• Sei stato assunto a causa delle tue capacità di programmatore
• Il tuo manager non ha queste competenze
• Ergo, il tuo manager non dovrebbe ragionevolmente aspettarsi di essere in grado di comprendere appieno quello che fai

Ho avuto un'esperienza simile a questa in un precedente lavoro. Il mio manager era un contabile (e quindi orientato ai dettagli di livello molto basso) e non capiva o non si fidava veramente della programmazione. Non riusciva a capire che lei, in quanto persona non tecnica, non avrebbe dovuto aspettarsi di riuscire a cogliere la minuzia di ciò che ho scritto. Dopo molte richieste di documentazione eccessiva e richieste di formazione di utenti non tecnici su come gestire e modificare il codice (sì, davvero), ho smesso di cercare di fobla, e mi sono completamente rifiutato. L'analogia che ho usato per spiegare era semplice:

• Non sono un ragioniere
• Non dovrei aspettarmi di comprendere ogni singola transazione o registrazione nei nostri conti
• Questo non significa che i conti siano sbagliati o inaffidabili, semplicemente perché non li capisco
• Ciò è reso possibile dalla fiducia della persona che li ha compilati

Alla fine, ecco come mi sembra: un manager che ha difficoltà a fidarsi dei propri dipendenti; o teme che se ne vadano e pensa che questo sia un modo efficace per mitigarlo.

L'unica soluzione a questo è sedersi e spiegare perché questo non ha senso. Il tuo compito è comprendere il codice e consentire a qualcuno con un'abilità simile alla tua di capirlo, non quello del tuo manager. Mostrare loro questa discussione potrebbe essere una buona idea (o davvero, davvero terribile, a seconda della loro personalità).

Linea per linea, è ridicolo. Quello che potrei suggerire è offrire di generare documenti dai commenti e darglielo. Ciò è stato sufficiente per una serie di sovvenzioni e audit del governo canadese su cui ho lavorato in passato.

Non otterrà riga per riga ma otterrà metodo per metodo che dovrebbe essere ancora più granulare di quanto gli serva.

Alcune soluzioni esistenti, a seconda della piattaforma:

• C #: castello di sabbia
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (Corba e Microsoft flavours), Fortran, VHDL, PHP, C # e in una certa misura D." : doxygen

Sarebbe molto più veloce per lui imparare a leggere il codice piuttosto che tradurre l'intero codice di qualsiasi applicazione interessante in inglese. Inoltre, l'abbiamo provato con COBOL e non ha aiutato affatto. Se non è disposto a imparare, ma vuole solo rendere la sua ignoranza il problema di qualcun altro, hai un capo seriamente appuntito.

Usa la tua competenza tecnica per perseguire il tuo capo.

1. Fagli sapere che ci vorrà tanto tempo per farlo, così come hai fatto per codificarlo in primo luogo (sentiti libero di allungarlo.).
2. Chiedigli quanto deve essere aggiornato questo documento. Informalo che ora tutte le modifiche alla codifica impiegheranno almeno il doppio.
3. Se tu o qualcun altro trovi dei bug, chiedigli se dovresti risolverli ora o attendi fino a quando non hai finito la codifica psuedo. Ricordagli di # 1 e # 2.

Come tutti i suggerimenti di soluzioni sbagliate, è meglio identificare il problema. Forse il tuo capo viene colpito da domande tecniche da parte dell'alta direzione e si sente imbarazzato dal momento che non è in grado di rispondere. Potrebbe esserci una particolare sezione di codice di cui si sente maggiormente preoccupato, quindi potresti limitare questa enorme impresa a quella zona.

Inviando un campione, potrebbe giungere alla conclusione che se non capisci come funziona la codifica (cos'è un loop e cosa sta facendo a tutti questi elementi?) Non importa in che lingua è. Sta meglio comprensione dell'applicazione da una prospettiva di power user. Penso che sia giusto per te fargli sapere che preferiresti scrivere un vero codice / suggerimento: sto cercando un altro lavoro.

Perché?

Un commento riga per riga non ragionevole, ma ecco cosa vorrei chiedere: perché lo vuoi?

È perché ...

• vuoi una completa comprensione di ciò che fa il software (non necessariamente come)?
• vuoi essere sicuro che un altro programmatore possa ritirare il progetto se me ne vado?
• vuoi vedere che sto facendo un vero lavoro?

Potrebbe esserci un ragionevole desiderio dietro questa richiesta, e potresti essere in grado di rendere felice il tuo capo capendolo e soddisfacendo quella necessità.

Aggiornare

Sulla base del Mikey'scommento, forse l'ho dichiarato un po 'troppo bruscamente. Non voglio dire che dovresti letteralmente dire "perché lo vuoi?", Solo che dovresti scoprirlo . La formulazione e il tono della voce fanno la differenza. In particolare, potresti dire qualcosa del tipo:

"Ho pensato alla tua richiesta di avere una spiegazione di ogni singola riga di codice. È un po 'insolito fare le cose in quel modo. Mi chiedevo se forse c'è qualcosa che non ti sto comunicando bene sul mio lavoro. Che cosa vuoi veramente capire sul nostro codice o su quello che sto facendo? Cosa stai cercando di realizzare qui? "

Certo, è possibile che il tuo capo sia totalmente irragionevole. Ma è più probabile che non sappia quanto sia stravagante questa richiesta e abbia in mente un obiettivo razionale.

In caso contrario, inizia a lucidare il tuo curriculum. :)

Sembra una buona occasione per provare la programmazione alfabetica. Google. :)

Ma ... non è necessariamente una richiesta del tutto irragionevole. Parte del tuo lavoro (la parte più importante, imo) è quella di comunicare i tuoi algoritmi ad altri sviluppatori e, se necessario, a persone non tecniche. Penso che i programmatori geniali solitari che non sono in grado di comunicare siano sempre problematici.

A tal fine, il tuo codice dovrebbe essere maledettamente chiaro (significato: o veramente auto-documentante o ben documentato, e per "auto-documentazione" intendo che variabili e funzioni hanno un significato o una responsabilità e il loro nome lo riflette chiaramente). Il tuo capo potrebbe avere buone ragioni per la sua richiesta. Forse (sto solo indovinando qui) tu o il tuo predecessore avete una reputazione per codice impenetrabile e fragile e questo è il rimedio del vostro capo. È un po 'estremo, ma potrebbe essere un esercizio utile per te. Suppongo che sappia che ci vuole tempo per scrivere documenti migliori (e se non lo fa, dovrebbe essere educato - è proprio come scrivere un termine: impiega più tempo a scrivere che a leggere).

Anche una traduzione riga per riga non trasmetterà efficacemente il significato di ciascuna riga di codice. Una comprensione da parte dei programmatori di una riga di codice è sempre nel contesto di molti fattori. Entra in qualcosa come un pezzo di codice multi-thread e la traduzione in inglese non avrà più senso del codice non elaborato. Pensa alla funzionalità che si sviluppa tra più funzioni / file. Alcuni codici non hanno assolutamente senso senza spiegare ampie quantità di altri codici. Cerca di spiegare le diverse parti coinvolte nell'iniezione delle dipendenze "riga per riga" e capirai cosa intendo. Quasi tutto ciò che va oltre il codice procedurale di funzione di Dio richiederà una grande quantità di conoscenze di programmazione solo per comprendere la traduzione inglese. Inoltre, guarda qualcosa di semplice come una dichiarazione di decisione if / else. Non esiste riga per riga, poiché la riga successiva dipende dai dati di runtime. La riga successiva potrebbe essere una delle diverse possibilità.Quando avrai spiegato cosa fa la tua candidatura, avrai trasformato il tuo PM in un programmatore e avrai entrambi 5 anni più vecchi.

Da quando insegnavo programmazione, sarei troppo felice di provarlo.

Scoprirà rapidamente che sta ottenendo più di quanto si aspettasse, il che mi renderà triste perché mi piace spiegare le cose :-)

Quando fai riferimento al tuo "Capo", si tratta di "un dirigente intermedio responsabile di te / della tua squadra"? o Il proprietario della tua azienda? Sei pagato "a ore" o "con uno stipendio"?

SE il tuo capo è un dirigente di livello intermedio che è responsabile, PARLA CON IL SUO BOSS, sottolinea che per soddisfare i requisiti del tuo capo la tua produttività per l'azienda sarà ridotta a 1/3 di quello che potrebbe essere.

Se il tuo capo è "il tipo che firma gli assegni" gli spieghi la stessa cosa, solo più diplomaticamente. Il tuo lavoro è passato da "Scrivi il codice" a "Scrivi il codice, scrivi la spiegazione del codice, spiega la spiegazione".

Un diagramma di flusso sarà probabilmente più vantaggioso per lui. Questa è certamente una richiesta insolita e non dice molto su di lui come manager.

Il fatto che il tuo capo sia disposto a dedicare un po 'di tempo alla comprensione del codice che hai scritto, potresti utilizzarlo a tuo vantaggio. Prova a presentarlo a Cetriolo: http://cukes.info/

e far scrivere al tuo capo BDD per te in futuro.

Non dovrebbe preoccuparsi di sapere nulla di tutto ciò. Digli che l'implementazione dello sviluppo software è soggetta a modifiche. Il design degli eventi è soggetto a modifiche. Raccontagli di nascondere informazioni, incapsulamento e astrazione. E anche dover fare questo tipo di lavoro ridurrà la tua efficienza. Non solo dovrai apportare successive modifiche in due luoghi diversi, ma avrà anche un impatto negativo sul morale del tuo lavoro, il che ridurrà ulteriormente la tua produzione.
Come parte del tuo team, come cliente del tuo codice, in senso lato, dovrebbe lavorare solo con un'astrazione chiara e di alto livello di ciò che fa il tuo codice. Allo stesso modo qualsiasi livello del codice funziona con un altro livello del codice di qualcun altro. Sapere qualcosa di più, lo rallenterà e rischierà di fare ipotesi basate sul funzionamento interno del tuo codice. Quelle ipotesi cesseranno di essere valide, quando si dovrà cambiare il codice, il che diventa un problema, se ha creato qualsiasi tipo di sistema o processo basato su di esse.

La bellezza dell'inglese è che si confonde magnificamente. Se lo usi a tuo vantaggio, potresti non riuscire mai più a gestire questo tipo di richiesta. Vorrei prendere un piccolo pezzo di codice come esempio, ma uno che è molto astratto e per niente facile da capire. Vorrei quindi scrivere i commenti in inglese tecnico come se lo stessi scrivendo per un capitolo di un libro di programmazione. Più è lungo e complicato da seguire, meglio è. Digli quante ore hai impiegato per documentare questa caratteristica. Spiega quindi che è solo 1/10 dell'1% (se possibile, utilizza cifre reali basate su righe di codice, probabilmente sono peggio di così) della base di codice effettiva. Quando si rende conto di non avere idea di cosa dice la traduzione in inglese e che ci vorranno 20.000 ore-uomo per fare questo livello di documentazione, si ritirerà abbastanza rapidamente. Ma cerca seriamente di compiere il suo compito. Non provarlo se non riesci a farlo e sospetta che tu lo stia interpretando.

Sembra un candidato per una striscia di Dilbert con il capo dai capelli appuntiti per una vacanza speciale ! La sua richiesta di certo non suona ragionevole a prima vista.

Umorismo a parte, cerca di scoprire di cosa ha davvero bisogno e perché, quindi avvisalo di quanto costerà in dollari o ore per darglielo, e lascia che decida se vuole spendere così tanti soldi.

Per quanto riguarda te stesso, conta le ore che ti ci vorranno per soddisfare la sua richiesta apparentemente bizzarra e quindi determinare se non sarebbe meglio investire una frazione di quel tempo nel trovare un nuovo lavoro lavorando per un datore di lavoro disposto a trattarti come professionista!

Portalo nel tuo ufficio e fatti fare un giro del tuo codice.

Si renderà conto a metà del fatto che ha fatto una richiesta assurda, e se ne andrà e non ti disturberà mai più.

Se non ti arrendi nelle sue richieste per aiutarlo a capire il tuo codice, troverà modi diversi ma ugualmente assurdi per prenderti in giro.

Questo è un caso in cui la pacificazione funziona meglio dell'abrasione.

Sarebbe molto bello se avessimo un traduttore "Language X to English" che lo fa. Allora uno potrebbe sorridere e dire, nessun problema, capo, lo avrai tra un minuto. E poi arriva una mail con alcuni megabyte di testo che recita:

• Sia un nuovo array intero con 20 elementi.
• Lascia che x sia una variabile per memorizzare numeri interi.
• Impostare x su 0
• Mentre x è minore di 20, fai ciò che è prescritto nelle prossime 2 righe
• imposta l'elemento array di a con l'indice x sul risultato della chiamata a nThPrime con l'argomento x + 1
• aumentare x di 1
• ....

Un'altra opzione sarebbe quella di suggerire la programmazione in Shakespeare d' ora in poi.

Il mio capo vuole una spiegazione inglese narrativa riga per riga del nostro codice

Difficile.

Dal momento che non è un programmatore, non può seguire il codice, quindi vuole che tutto sia tradotto in inglese.

Se non è un programmatore, non dovrebbe leggere il codice. Affatto.

Fornire invece documentazione di alto livello.

Questa non è una richiesta ragionevole, vero?

No.

Come programmatore, hai davvero "due" lavori.

Il primo è creare buoni programmi. Il secondo è "venderli" ai clienti all'interno e all'esterno dell'azienda.

La richiesta del tuo capo "fa male" al tuo primo lavoro. Ci vuole più tempo per documentare i tuoi programmi. D'altra parte, ti sta effettivamente facendo lavorare di più per il tuo "secondo" lavoro.

Il tuo capo ti sta chiedendo di documentare il tuo programma in inglese a beneficio dei SUOI, e presumibilmente a beneficio delle persone con cui ha a che fare, all'interno e all'esterno dell'azienda. Se lo aiuti a fare il suo lavoro, dovrebbe funzionare a tuo vantaggio a lungo termine, quando gli chiedi più hardware, personale o denaro per i rilanci. Dopo tutto, ti ha chiesto di fare più lavoro.

Penso che BDD si adatterebbe bene a questo problema, anche se sembra che il tuo progetto sia quasi completato, quindi è un po 'difficile implementarlo adesso, quindi è più come riferimento futuro.

Con BDD i casi d'uso sono descritti come documenti leggibili umanamente che vengono poi tradotti in test funzionali automatizzati.

Probabilmente, questa richiesta è un buon momento per imparare cose come ANTLR . Prendi ANTLR, prendi la grammatica della tua lingua, analizza tutto il codice che hai, attraversa il tuo AST generando descrizioni basate su template per ogni nodo, così i++viene descritto come increase i by 1 using postfix increment operator. Dovrebbe essere davvero divertente. Il tuo capo potrebbe anche voler includere questo strumento nello script di compilazione, quindi ogni volta che apporti delle modifiche, riceverà un'e-mail di ~ 20 MB che descrive cosa fa la nuova versione.

PS Sto solo scherzando, è un idiota.

Anche se sono d'accordo che questa è una richiesta irragionevole, il tuo capo potrebbe apprezzare qualcosa come l'output di Docco , che separa il tuo codice e i commenti riga per riga o clausola per clausola in output HTML a due colonne, con il codice su uno lato e prosa dall'altro. Devi digitare tu stesso i commenti, ovviamente, ma la presentazione è piuttosto bella IMHO, anche per i lettori non tecnici. Vedere, ad esempio, una sezione commentata riga per riga del codice annotato per Underscore.js . Esistono anche versioni di script Python e shell.

È possibile che il tuo capo sia semplicemente disinformato e intimidito, ma in realtà è una persona ragionevole. In tal caso, il ragionamento con lui / lei potrebbe funzionare - una conversazione informale in cui prometti di fornire "ciò che vuole veramente", ad esempio; una guida in prosa a ciò che il programma sta facendo.

Se si tratta di "la mia strada o l'autostrada" è meglio controllare il gas ora.

Potresti scrivere alcuni test di accettazione utilizzando un framework di progettazione orientato al comportamento come il cetriolo ? Questo non spiegherà il codice; spiegherà cosa fa e in linguaggio naturale. Ha anche il vantaggio di essere eseguibile, quindi puoi sempre essere sicuro che la documentazione sia aggiornata, perché se non lo è, il test-runner sarà rosso.

Guarda il video introduttivo. Forse è un buon diversivo mentre trovi un nuovo capo ... ;-)

Il tuo manager è quasi certamente angosciato dal fatto che non capisce cosa fanno le persone che sta gestendo, e non ha le basi per capire i risultati che producono.

Dubito che abbia pensato a questa soluzione in modo molto approfondito, e probabilmente gli è sembrato ragionevole a prima vista. Ma questo è in gran parte perché non capisce cosa sia effettivamente il codice di programmazione.

Qualsiasi programmatore comprende l'assurdità di questa richiesta, ma lo facciamo perché sappiamo intuitivamente che una volta superata la lingua, tutto ciò che viene rivelato è l'algoritmo, che è ugualmente criptico.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Il problema qui è che mentre i commenti spiegano cosa fa ogni riga, non hai ancora idea di cosa faccia realmente il codice se non capisci quali sono tutte le implicazioni. È ovvio se sei un programmatore e hai già visto questo schema prima; ma mostralo a qualcuno che capisce solo le vendite e sarà altrettanto confuso dopo aver letto i commenti come prima.

In realtà potresti risparmiare tempo insegnando al tuo capo una programmazione di base. Se vuole leggere il tuo codice, dagli gli strumenti per poterlo fare. La maggior parte delle lingue sono abbastanza sintattiche e l'apprendimento della struttura richiede solo un'ora o due. Quasi sicuramente si arrenderà dopo qualche giorno, ma almeno saprà cosa sta trasmettendo e, soprattutto, perché non vuole leggere il tuo codice.

IMHO ... se è responsabile del completamento dell'attività, dovrebbe sapere come funziona ... :)