Il mio cliente desidera il 25% dei commenti nel mio progetto attuale, come reagire? [chiuso]


96

sviluppatore junior qui.

Attualmente sto lavorando da solo su un'applicazione web per un grande cliente della mia azienda. Ho iniziato il mese scorso. Il cliente desidera almeno il 25% dei commenti in ciascuno dei suoi progetti software.

Ho controllato il codice delle precedenti domande ed ecco le mie osservazioni:

  • ogni file inizia con un blocco di commenti (pacchetto, data dell'ultimo aggiornamento, nome della mia azienda e copyright)
  • tutte le variabili sono commentate con i loro nomi // nameOfCustomer public String nameOfCustomer

  • tutti i getter e setter sono commentati

  • pochissimi commenti utili

Sembra che gli sviluppatori inseriscano il maggior numero di commenti possibile per raggiungere quella soglia del 25%, indipendentemente da qualità e utilità. La mia azienda mi dice che "lo facciamo come vuole il cliente".

Non ho parlato direttamente con il cliente di questo. Ecco i miei argomenti finora:

  • righe inutili da leggere e da scrivere (perdita di tempo)
  • i commenti a volte non vengono aggiornati (fonte di confusione)
  • gli sviluppatori hanno meno probabilità di utilizzare o fidarsi di commenti realmente utili

Qual è il tuo consiglio su questo argomento? Come dovrei gestire la situazione?


162
È ridicolo. Tuttavia, se questo è ciò che il cliente desidera e il cliente ti sta pagando un buon prezzo per ottenerlo, allora è quello che gli dai.
Robert Harvey,

20
25% di righe (ovvero non inserire mai un commento sulla stessa riga del codice) o 25% di byte ?
Ron John


10
Meglio stare attenti qui. Di solito c'è un motivo dietro questo tipo di aspettativa ... Se dici ai tuoi clienti che quei commenti sono inutili, lui / lei potrebbe ancora voler commenti del 25% (con qualunque motivo abbiano) ma ora SENZA quelli che chiami inutili ..
Potresti

19
Questa è una lezione oggettiva in una regola che avrai ampie opportunità di osservare nella tua carriera: la cosa che misuri è quella che ottieni . Ti è stata data una metrica per i commenti, e quindi i commenti sono la cosa che otterrai. Un cliente più sensibile ti darebbe metriche per prestazioni, correttezza, solidità e costi, e poi otterrai quelle cose. Ma non hai un cliente sensibile.
Eric Lippert,

Risposte:


115

Tutte le altre risposte e commenti qui mi hanno davvero messo in discussione, perché sono così contrari alla mia prima reazione e così contrari all'atteggiamento a cui ho assistito nei miei colleghi. Quindi mi piacerebbe descrivere un approccio alternativo, anche solo per il gusto di essere la voce dissenziente .

Il principio guida di questa risposta è "Delizia il cliente". Deliziare il cliente non significa solo soddisfare le sue aspettative; significa comprendere le loro richieste così profondamente che puoi interpretare ciò che dicono nel modo in cui lo significano, e consegnare al di là di ciò che chiedono. Altre risposte sembrano essere guidate dal principio di conformità malevola, che trovo disgustoso; e inoltre è discutibile pratica commerciale in quanto è un brutto modo per ottenere clienti abituali.

Per me, quando sento il cliente dire "Voglio commenti al 25%", questo è l'inizio di una finestra di dialogo. Per me è chiaro che qui le implicazioni sono "Voglio un sacco di testo descrittivo, in modo che i nuovi arrivati ​​a questa base di codice possano iniziare a funzionare rapidamente", non "Voglio che tu aggiunga casualità in una certa categoria sintattica" come altre risposte sembra prenderlo. E prenderei sul serio quella richiesta, e intendo scrivere molti commenti descrittivi e utili, guidando un nuovo arrivato alla struttura del codice, sottolineando decisioni ingegneristiche sorprendenti e delineando il ragionamento che ne è derivato, e dando un inglese di alto livello descrizioni di sezioni di codice complicate (anche se non hanno sorprese). Questa intenzione e comprensione è il punto di partenzadella discussione - cioè prima ancora di iniziare a parlare. Per me l'implicazione della richiesta è così chiara che non ha nemmeno bisogno di quel chiarimento; ma se per te non è chiaro dovresti ovviamente verificare con loro!

Va bene, quindi dove va la finestra di dialogo se questo è il punto di partenza? La parte successiva della finestra di dialogo è la seguente:

  1. Mi aspetto che ciò costituisca uno sforzo supplementare serio, probabilmente in una seconda fase del progetto, che va al di là della produzione dello strumento a cui tengono. Potrebbero essere necessari diversi minuti di discussione per discutere di questo processo e perché è un lavoro aggiuntivo, ma lo ometterò qui perché come programmatore professionista mi aspetto che tu sappia quanto sia difficile fare buoni commenti.
  2. "Un serio sforzo aggiuntivo" significa che potremmo aver bisogno di un budget più lungo e di un budget maggiore; o potrebbe essere necessario ridurre il budget delle funzionalità; opotremmo dover scendere a compromessi sulla qualità e la quantità dei commenti. Questa parte sarà un po 'una trattativa. Ma a mio avviso, dovresti essere molto in anticipo sui costi di fare questo lavoro extra e assicurarti che sia una caratteristica così importante per il cliente che sono disposti ad assumersi questi costi. E se lo sono - fantastico! Ottieni tempo e denaro extra e ottengono commenti di alta qualità. Tutti vincono. E se si scopre che la funzione di commento non è così importante per loro che sono disposti a perdere la capacità di spurgare i widget o disposti a lasciare che la scadenza scada a fine gennaio, 20x6, allora tutti vincono di nuovo: ottengono il prodotto che desidera e non è necessario dedicare lo sforzo supplementare necessario per creare commenti di alta qualità.

Ecco dove penso che la finestra di dialogo non dovrebbe andare:

  1. Non minacciare il cliente con commenti di bassa qualità. Lascia che ti aiutino a scegliere il livello di sforzo che vogliono spendere e che sono disposti a pagare. Non promettere loro commenti del 25% e poi informali che intendi mantenere questa promessa generando casualmente la casualità dopo la creazione del progetto.
  2. Non nascondere i tuoi piani. Non promettere loro il 25% dei commenti, quindi autogenerare la casualità senza dire loro che è quello che farai. Quando notano (non se), entrambi perdono alla grande: non sono soddisfatti del prodotto che hanno ricevuto e si ottiene un passaparola negativo.
  3. Non cercare di convincerli che non vogliono commenti. Vogliono chiaramente commenti. Discutere sui compromessi di vari approcci: sì! Discutere modi alternativi per rendere la base di codice amichevole per i nuovi arrivati: sì! Di 'loro che non sanno cosa vogliono: eh, no. Vuoi lavorare con loro per ottenere loro ciò che vogliono; quindi capisci di cosa si tratta e cerca il modo migliore per consegnarglielo con un budget che approva, dando la priorità alle funzionalità a cui tengono di più se le risorse che hanno sono insufficienti.
  4. Non fare scuse su quanto siano difficili i commenti da scrivere. Scrivere codice è difficile; il codice di debug è difficile; scrivere commenti è difficile. Se fosse facile, non ti assumerebbero. Basta saltare i reclami e arrivare direttamente al punto a cui tengono, ovvero come lo sforzo extra richiesto li influenza.

3
Bella presa positiva sulla domanda :-)
cmaster

9
@ThorstenS. La società per cui lavoro fa una grande maggioranza del suo lavoro per l'industria della difesa. Potrebbe voler controllare i tuoi poteri psichici. Inoltre, non ho mai detto "non interpretare i loro desideri come l'hanno scritto": tratterei i "commenti del 25%" come una richiesta seria ma incidentale - la vera richiesta è "un ampio corpus di testi tecnici", e il 25% è solo un'indicazione del livello di sforzo che si aspettano di entrare in quel corpo, probabilmente scelto essenzialmente in modo arbitrario, ma tuttavia un obiettivo da non perdere.
Daniel Wagner,

12
Se assumessi un programmatore, il signor Daniel Wagner è il tipo di ragazzo che vorrei assumere.
Joe Gayetty,

5
Questa è un'ottima risposta in quanto cerca di identificare e affrontare l'intento della richiesta rispetto alla lettera della richiesta. IMO Questa è la differenza tra uno sviluppatore e qualcuno che scrive semplicemente codice.
Justin Ohms,

6
Sarebbe inoltre opportuno chiarire che questi commenti aumenteranno i costi di manutenzione . Una volta creati, devono essere costantemente aggiornati o sono una perdita di tempo e denaro. (Aspettando fino a domani a +1 in modo da ottenere effettivamente il rappresentante.;) Te lo meriti.)
jpmc26

83

Il cliente è re. Quindi, come appaltatore, dovrai soddisfare qualunque cosa il cliente abbia definito standard di qualità. O rischi di uscire.

Detto questo, importa molto come vengono definiti gli standard di qualità (qui poveri):

  • Standard di qualità contrattuali: il codice consegnato deve essere conforme, altrimenti è una violazione del contratto. Nessuna scelta.

  • Standard formali di qualità aziendale: anche se funziona perfettamente, il codice non conforme sarà considerato di cattiva qualità da così tante persone, che sarai vecchio prima di convertirli tutti in una pratica migliore. Peggio ancora: strumenti ben noti possono essere utilizzati per automatizzare e legittimare tali parametri di qualità (ad es. Cubo sonar ). Quasi nessuna scelta.

  • Criteri ad hoc definiti da un paio di persone presso il cliente. Qui potresti coinvolgere la discussione. C'è speranza :-)

In quest'ultimo caso, potrebbe esserci una certa flessibilità e potresti provare a fare diplomaticamente il punto. Ecco alcuni argomenti che parlano contro i criteri del cliente:

  • Problema di produttività: la codifica viene eseguita due volte (una volta in inglese e una volta in codice).
  • Problema di precisione: se vengono apportate modifiche nel codice, devono essere apportate nei commenti o i commenti potrebbero diventare inutili.
  • Problema di refactoring: come strumento di refactoring non elabora i nomi delle variabili nei commenti.
  • Problema di rischio: l'ambiguità (o l'obsolescenza) dei commenti potrebbe generare confusione e rischio di aumentare i bug.
  • La quantità non è qualità
  • Questa divertente raccolta di commenti inutili su StackOverflow .
  • Questo articolo sostiene che un alto rapporto di commento potrebbe persino essere il segno di un odore di codice.

Ma invece di parlare contro il male e confrontarsi con il cliente, potresti semplicemente promuovere approcci migliori:

  • Codice pulito (suggerisci il libro al tuo cliente: c'è una sezione convincente dedicata ai commenti e al codice autocompensante).
  • Pratica della documentazione: le cose più difficili da comprendere, e quindi le informazioni più preziose, come ad esempio la relazione e l'interazione tra le classi, sono meglio documentate in un documento separato (ad esempio in un'immagine UML piuttosto che in 1000 parole di commento?)

Se il cliente non è ancora convinto, è possibile proporre un'alternativa sperimentale, utilizzando strumenti che generano automaticamente la documentazione con commenti, come javadoco doxygen. Proponi con ciò di spostare l'attenzione dalla quantità (25% di codice) alla qualità (generare un javadoc comprensibile).


7
Se il cliente è il re, ciò dimostra quanto siano inefficienti tali regalità del cliente!
Steve

82
" Il cliente è il re. Quindi, in qualità di appaltatore, dovrai soddisfare qualunque cosa il cliente abbia definito standard di qualità. O rischi di essere fuori. " Il contrario è stata la mia esperienza. Coloro che danno ai loro clienti ciò che pensano di desiderare e non ciò di cui hanno effettivamente bisogno non sopravvivono a lungo. In effetti, riservo questa forma di abuso solo ai clienti con problemi reali e non è mai stata necessaria una seconda dose.
David Schwartz,

6
@DavidSchwartz sì, certamente. A volte i clienti pensano di aver bisogno di qualcosa ma ne hanno davvero bisogno di un altro. Spetta al consulente o allo sviluppatore convincere, e 2/3 della mia risposta riguarda esattamente questo. Ma tutto dipende dal contesto contrattuale e dal livello di fiducia tra il fornitore e il cliente. Quindi la regola del cliente è re deve essere ricordata (in effetti ho sperimentato più volte con i clienti, che dopo un lungo dibattito sulla soluzione ottimale, ho sollevato questa frase e che ha innescato un improvviso cambio di atteggiamento e un attento riesame degli argomenti ;-) ).
Christophe

7
"Problema di precisione: se vengono apportate modifiche al codice, devono essere apportate nei commenti o i commenti potrebbero diventare inutili." Direi che è anche peggio che semplicemente inutile . Un commento che non è aggiornato potrebbe trasformarsi in un bug (o qualcuno che lo ripristina perché pensa che sia un bug) molto velocemente quando ti aspetti che sia la fonte della verità e ti fidi di esso.
Hamatti

11
@Hamatti In effetti. Una volta ho trascorso una considerevole quantità di tempo a decifrare l'intento originale dietro una riga che recitava,i++; // count down
TKK

18

Il cliente desidera almeno il 25% dei commenti in ciascuno dei suoi progetti software.

Il cliente desidera davvero il 25% dei commenti o desidera che il codice sia il più descrittivo possibile?

IMHO, il cliente sa cosa vuole, ma non di cosa ha bisogno. Poiché un cliente non è uno sviluppatore stesso e riceve feedback dai propri lavoratori / clienti, il cliente vede solo la parte superiore dell'iceberg.

Immagino che il tuo cliente abbia qualche pseudo-conoscenza e desideri che il codice sia ben documentato, facile ed economico da mantenere, e lo strumento per questo sono i commenti (nella sua mente).

Prova a parlargli e prepara alcuni frammenti di codice con un codice ben scritto che spiega se stesso e un altro scritto male con commenti. Solo poche righe. Mostralo se necessario e usalo come immagine per le tue parole.

Parla con il tuo cliente / supervisore / qualunque cosa e prova a dire loro i moderni principi di controllo della versione (non c'è bisogno di commenti all'inizio del file) e il codice pulito (consiglio anche il libro ) e quindi il codice che si spiega da solo.

Forse, se riesci a mostrarlo abbastanza bene e far capire al tuo cliente che vuole un codice pulito, non solo commenti, tu e il tuo team potete scrivere codice migliore (con molti meno commenti) e dimostrare immediatamente che siete un buon sviluppatore che vale la pena tenere .


13
Il codice autoesplicativo è un principio adorabile. Purtroppo però non funziona così bene nel mondo reale. Interfacce e processi interni complessi devono essere documentati e semplicemente scegliere nomi carini non è abbastanza buono. Quali unità sono quei valori? Fattori di ridimensionamento? Frequenze di campionamento? Quando è sicuro chiamare quel metodo e quando no? Quali eccezioni vengono generate per quali condizioni? E così via, e così via. Questo è ciò che rende il tuo codice mantenibile. Il mondo reale ha una complessità che uno snippet di codice non rappresenterà mai, ed è per questo che è necessario documentarlo correttamente.
Graham,

2
@Graham Sì, i commenti non sono assolutamente inevitabili. Ma i commenti sono come il codice: più fai, più deve essere mantenuto. Rimanere conciso aiuta a credere.
Robert Dundon,

Non voglio dire che alcuni elementi siano completamente inutili, ma i commenti esattamente come il nome della funzione o della variabile non sono utili. La breve parte di codice dovrebbe mostrare che è possibile senza commenti e non dovrebbe imporre un ambiente privo di commenti. Se si desidera mostrare quali eccezioni vengono generate o descrivere ulteriormente la funzionalità, è possibile utilizzare il tag di riepilogo per le funzioni. Se vuoi segnalare dipendenze, modella l'oggetto necessario come parametro di input ecc. Non esiste un modo perfetto per fare tutto, ottieni il meglio da entrambi i mondi
Chrᴉz

@Chriz Assolutamente, sono d'accordo. Se i commenti non aggiungono informazioni, lasciarle fuori. Ma come ho detto in un'altra risposta, la percentuale è davvero solo un test dell'odore del codice. Lo giustifichi, il revisore lo controlla, tutti vanno avanti. La preoccupazione è qualcuno che pensa che il proprio codice sia davvero autoesplicativo e non ha pensato a tutto quel genere di cose.
Graham

12

Questo mi ricorda quelle sciocche risposte Stack Overflow che vedi che consistono in una riga seguita, letteralmente, "un po 'di testo qui per arrivare al limite minimo di caratteri".

Quando ciò accade, si potrebbe sostenere che due gruppi di persone sono in errore:

  1. Le persone che mettono il limite - chiaramente è eccessivo e impedisce alle persone di presentare le loro informazioni correttamente formate senza aggiungere rumore artificiale

  2. Le persone che hanno inviato informazioni che non sono state formate correttamente, quindi hanno aggiunto rumore artificiale quando il sistema ha richiesto loro di aggiungere più sostanza effettiva

A volte, una domanda sarà tanto semplice e in argomento, e non c'è molto altro da dire che poche parole. Tuttavia, questo è estremamente raro. In quasi tutti i casi, c'è molto più di sostanza da dire. Se non altro, dovrebbe essere palesemente ovvio che il modo per aggirare una limitazione del personaggio non è semplicemente scaricare rumori casuali nel tuo post.

Questa situazione di commenti che stai affrontando è quasi la stessa. I tuoi sviluppatori hanno preso una richiesta di commenti e l'hanno implementata scaricando rumore casuale nel loro codice. Documentare i nomi delle variabili, proprio accanto alla dichiarazione delle variabili, è vandalismo . Ciò non avrebbe mai dovuto succedere.

"Ma come possiamo arrivare al 25%?" Scrivendo commenti concreti sulla sostanza. Usa più parole, parole migliori, le parole migliori per documentare l'effetto delle funzioni. Espandi le tue spiegazioni. Descrivere i casi limite in modo più dettagliato.

Tuttavia, tornando al punto originale, anche qui il cliente è parzialmente in errore, perché il "25% del codice sorgente" è estremamente arbitrario. Alla fine, però, sono il cliente, quindi sfruttalo al meglio. Ma intendo "il migliore". Non "peggio", come è successo finora.


5

Non so quale sia il grosso problema con questo requisito.

Solo per ossigenazione di base del tuo codice probabilmente sei già al 10% circa. E prendiamo un altro 5% dei commenti che hai scritto per te (alcuni scrivono di più, ma il 5% sembra una stima prudente se non hai fatto voto di silenzio). A questo punto è circa il 15% (sì sì, lo so, il 5% del 90% è inferiore al 5%, non fare il pignolo). Se il tuo doxygen è inferiore al 10%, forse i tuoi metodi sono molto lunghi; di solito è una buona idea suddividerle in classi più piccole (principalmente private / protette) o utilizzare classi di supporto più generiche ecc.

Ora, per il resto del testo dei commenti, inserisci considerazioni di progettazione e scenari di utilizzo nei commenti a livello di classe / file. Avere alcune tabelle o ASCII-art (o codice doxygen che genera roba di aspetto più bello quando viene renderizzato). Ovviamente non so di cosa tratta il tuo progetto, ma credo che tu possa farlo senza commenti fittizi (oltre alla piastra di ossigenazione) e arrivare a qualcosa di vicino al 25%.

Se è solo, diciamo, il 20% e non il 25%, sono sicuro che il cliente ha appena dato quel numero come qualcosa di arbitrario e andrà bene. Comunque, parla con loro per discutere di cosa dovrebbero includere i commenti; e mostra loro un esempio di file commentato per vedere se sono contenti. Se lo sono allora è così, se pensano che manchi qualcosa ti diranno cosa manca. Non ti diranno "Non possiamo suggerire alcun possibile commento aggiuntivo ma vogliamo ancora che tu ne aggiunga un po '".

PS: guarda il codice dei contenitori Java standard per vedere come puoi raggiungere, oh, il 70% o giù di lì ...


5

Avere il 25% di commenti nel codice è un obiettivo eccellente da raggiungere e rende felice il cliente. Ora scrivere commenti scadenti del 25% come "i + = 1; // aumenta i di 1" dovrebbe essere sotto di te, quindi prenditi il ​​tuo tempo, scrivi commenti utili e goditi la sensazione che sei effettivamente pagato per fare qualcosa che dovresti fare Comunque.


Anche quello è bello +1. Non so se può esserci un buon obiettivo espresso in termini di percentuale di commenti, ma forse molti di noi raggiungono questo '' obiettivo '' in modo utile, senza sapere ... Recentemente ho ritrovato un vecchio pezzo di codice che ho scritto negli anni '80 all'inizio della mia carriera, con un algoritmo innovativo ad alte prestazioni: ha solo il 10% di commenti, ma retroattivamente, vorrei averne messo solo di più ;-)
Christophe

4

Sappiamo tutti che questo è un requisito di merda. La domanda interessante qui è

come reagire?

Sono un grande sostenitore nel rendere visibili i problemi. Qui userei il fatto che il denaro parla.

Chiedimi di fare questo e dirò certo che aggiungerà l'1% alla mia offerta. Oh, ma aggiungerà il 20% a eventuali offerte di manutenzione future.

Solo una volta mi chiederanno perché insegnerò loro che il punto dei buoni nomi è evitare la necessità di commentare.

In alternativa, proporrò di creare la documentazione volta a ottenere un programmatore di manutenzione con un set definito di qualifiche presunte per accelerare le idee alla base del progetto. O certo, potrei darti il ​​25% dei commenti. Sta a te.


3

Sì, capisco la tua frustrazione per la regola sciocca. Ho letto molti programmi con commenti inutili come

x = x + 1; // add 1 to x

E mi dico, quindi QUESTO significa un segno più !! Wow, grazie per avermelo detto, non lo sapevo.

Detto questo, il cliente sta pagando il conto. Pertanto, dai loro quello che vogliono. Se avessi lavorato presso un concessionario di automobili e un cliente avesse detto che voleva un camioncino, non avrei discusso con lui sul fatto che avesse davvero bisogno di un camioncino e non lo interrogassi su ciò che si aspetta di trasportare. Gli venderei un camioncino.

Va bene, ci sono momenti in cui ciò che i clienti dicono che vuole e ciò di cui ha davvero bisogno sono così distanti che provo a discutere della questione con lui, magari a convincerlo a concordare qualcosa di più razionale. A volte funziona, a volte no. Alla fine, se non riesco a cambiare idea, gli do quello che vuole. Se ritorna più tardi e dice, Oh, che davvero non ha soddisfatto i miei requisiti aziendali, allora possiamo fargli pagare di più per fare ciò che gli abbiamo detto di fare la prima volta. Quanto puoi negoziare con il cliente dipende da quanto si fidano delle tue competenze, da come il loro contratto con te si adatta all'organizzazione e, francamente, da quanto sono corretti.

Sarebbe un caso molto raro in cui, supponendo che dipendesse da me, perderei un contratto perché pensavo che i requisiti fossero mal concepiti.

Tieni presente che le persone con cui la tua azienda sta negoziando possono o meno essere quelle che hanno inventato questa regola del 25%. Potrebbe essere una regola imposta loro dall'alto.

Vedo cinque possibili risposte:

Uno. Convincere il proprio capo o chiunque stia negoziando con il cliente per discuterne. Le probabilità sono che questo non compirà nulla, ma puoi provare.

Due. Rifiuta di farlo. Questo probabilmente ti farà licenziare, o se la società è d'accordo con te, ti farà perdere il contratto. Questo sembra improduttivo.

Tre. Scrivi commenti inutili per riempire lo spazio, il tipo di commenti che ripetono semplicemente ciò che è nel codice e che qualsiasi programmatore in grado di modificare il codice potrebbe vedere in 2 secondi. Ho visto molti commenti come questo. Anni fa ho lavorato per un'azienda in cui dovevamo mettere blocchi di commenti davanti a ogni funzione che elencava i parametri, come:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

L'obiezione che tali commenti sono un onere di manutenzione perché è necessario tenerli aggiornati non è valida. Non è necessario tenerli aggiornati perché nessun programmatore serio li guarderà mai. Se c'è qualche domanda a riguardo, assicurati di chiarire a tutti i membri del team che i commenti inutili e ridondanti dovrebbero essere ignorati. Se vuoi sapere quali sono i parametri di una funzione o cosa fa una riga di codice, leggi il codice, non guardare i commenti inutili.

Quattro. Se hai intenzione di aggiungere commenti inutili ridondanti, forse vale la pena scrivere un programma per generarli. Qualcosa di un investimento in anticipo, ma potrebbe salvare un sacco di scrivere lungo la strada.

All'inizio della mia attività, un'azienda per cui lavoravo utilizzava un programma pubblicizzato come "Scrive la tua documentazione per te! Documentazione completa per ogni programma!" Il sistema richiedeva che dessimo a tutte le variabili nomi sostanzialmente privi di significato e che quindi avessimo una tabella che fornisse un nome significativo per ogni variabile, quindi sostanzialmente ciò che la "documentazione automatica" faceva era sostituire il nome insignificante che ci costringeva a usare con un nome significativo. Quindi, per esempio - ha funzionato con COBOL - nel tuo programma avresti una linea che diceva

MOVE IA010 TO WS124

e genererebbero una linea di "documentazione" che diceva

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

Ad ogni modo, si potrebbe sicuramente scrivere un programma per generare abbastanza facilmente documentazione altrettanto inutile. Leggi una riga come

a=b+c

e genera il commento

// add b to c and save result in a

Eccetera.

Cinque. Ottieni il meglio dalla regola sciocca. Prova a scrivere commenti utili e significativi. Ehi, potrebbe essere un buon esercizio.

Oh, a proposito, posso aggiungere che puoi sempre giocare la metrica.

Ricordo che una volta un datore di lavoro aveva affermato che avrebbero iniziato a misurare la produttività dei programmatori in base al numero di righe di codice prodotte a settimana. Quando ci hanno detto questo in una riunione, ho detto: Fantastico! Posso facilmente aumentare il mio punteggio. Non più scrittura

x=x+4;

Invece scriverò:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Loops? Lascia perdere, copierò e incollerò il codice dieci volte. Eccetera.

Quindi qui, se contano le righe di commenti, accorcia ogni riga e continua l'idea sulla riga successiva. Se c'è una modifica a ciò che accade nei commenti, non aggiornare il commento esistente. Inserisci una data su di esso, quindi copia l'intero testo e scrivi "Aggiornato" e una nuova data. Se il cliente lo mette in discussione, digli che hai pensato che fosse necessario mantenere la cronologia. Ecc. Ecc.


2

Le metriche arbitrarie sembrano essere un dato di fatto in troppi progetti ...

Questo è spesso visto in requisiti stupidi come la massima complessità ciclomatica che porta a un codice più complesso, perché le funzioni sono inutilmente suddivise per garantire la conformità o i file vengono suddivisi perché superano una lunghezza SLoC arbitraria

I commenti dovrebbero aggiungere al codice e spiegare cosa sta succedendo (e non solo ripetere il codice!).

Detto questo, se questo è ciò che il tuo cliente desidera e la tua azienda ha accettato di fornire, a meno che il tuo Responsabile QA non sviluppi una dose di buon senso, sei bloccato.


Sì. Le regole arbitrarie portano le persone a modificare il proprio comportamento per trarre vantaggio dalla regola. Questo è il problema con la burocrazia. Mi sorprende il modo in cui le persone possono inventare una regola e non considerare che le persone che sono interessate dalla regola possano tenerne conto quando decidono cosa fare. Quindi fanno più regole per tappare le scappatoie e più regole per tappare le scappatoie create dalle scappatoie, ecc.
Jay

2

A breve termine non c'è nulla che tu possa davvero fare. Andare d'accordo con.

Dovresti anche ignorare tutte le idee stupide che sto vedendo in questo thread su proteste aggressive passive e battute stupide all'interno del codice.

Una volta che hai sviluppato una relazione di fiducia con il cliente, saranno nella posizione migliore per ascoltare il tuo ragionamento: potresti scoprire che questa è una domanda sciocca da una persona che una volta era influente e che ha un supporto molto piccolo interno.

In nessun caso dovresti andare contro di esso senza il permesso del cliente.


2

Sono deluso dalla mancanza di immaginazione mostrata dai miei colleghi programmatori qui.

Mi sembra che il cliente abbia fatto delle ricerche. Potrebbe aver letto da qualche parte che il codice di qualità in genere contiene circa il 25% dei commenti. Ovviamente si preoccupa / si preoccupa per la manutenzione più avanti. Ora, come può concretizzarlo in un documento di requisiti che deve essere legato a un contratto? Non è facile Potrebbe anche essere impossibile. Tuttavia vuole assicurarsi che otterrà un valore per i suoi soldi, quindi elenca alcuni indicatori di qualità.

Non mi sembra affatto stupido o ridicolo. Le persone che hanno scritto i requisiti probabilmente non sono programmatori. Potrebbero aver avuto una brutta esperienza con un progetto precedente. I loro addetti alla manutenzione si lamentano: "Nessuna di queste cose è documentata!". Sta suonando nelle orecchie mentre scrivono nuovi requisiti per il prossimo progetto.

Se sei seriamente intenzionato a documentare il tuo codice e a fornire un contesto per la banda di manutenzione, questo requisito sarà soddisfatto automaticamente. Quindi non fare la figa!

Alla fine, che si tratti del 21% o del 29%, a nessuno importa. Il cliente farà rivedere le tue cose da uno sviluppatore indipendente e capirebbe meglio cosa hai fatto.


1
La domanda dimostra definitivamente che esprimere un tasso di commento come obiettivo si ritorcerà contro. Sarebbe stato più efficace per il cliente avere come obiettivo obiettivo che il codice dovesse essere comprensibile da un altro sviluppatore (nel team? Dall'esterno? Con quali conoscenze e competenze di base?) E dare il 25% come linea guida (flessibile). Esprimerlo in questo modo sarebbe stato meglio compreso dagli appaltatori e incoraggiato alternative migliori, come il codice pulito.
Christophe

0

Ho incontrato molti programmatori che non capiscono come esistono le persone che attualmente non lavorano su questo progetto.

Per loro tutto ciò che sanno, È noto a tutti.

Se qualcuno non conosce TUTTO ciò che attualmente conoscono, allora quelle persone sono "idioti" per loro.

Con questo standard puoi costringere le persone ad appassionarsi alla scrittura di commenti.

Potrebbero scrivere commenti inutili il 99% delle volte, ma a volte potrebbero effettivamente scrivere una delle cose che "TUTTI CONOSCONO", e qualcuno che è nuovo nel team potrebbe effettivamente non passare 16 ore a cercare un bug (che qualcuno ha già risolto, ma poi è stato annullato per un altro motivo) che sarebbe stato ovvio con un commento a quel punto nel codice.

Avere commenti a righe con bug non visibili può anche aiutare a evitare che i futuri programmatori interrompano completamente un programma per errore (specialmente quando la parte "essere interrotta" non è ovvia quando si esegue un test rapido).


3
Il problema di far battere 10000 scimmie sulle macchine da scrivere non è che non scrivano mai qualcosa di prezioso, ma che quelle gemme evanescenti rare sono difficili da trovare nel mucchio di immondizia.
Deduplicatore
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.