Il mio cliente desidera il 25% dei commenti nel mio progetto corrente, 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 applicazioni precedenti e qui ci sono 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 i setter sono commentati

  • pochissimi commenti utili

Sembra che gli sviluppatori inseriscano quanti più commenti possibile per raggiungere la soglia del 25%, indipendentemente dalla 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:

  • linee inutili da leggere e scrivere (perdita di tempo)
  • I commenti
  • a volte non sono aggiornati (fonte di confusione)
  • gli sviluppatori hanno meno probabilità di utilizzare o fidarsi di commenti utili reali

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

    
posta Robin_ 05.03.2018 - 22:52
fonte

12 risposte

114

Tutte le altre risposte e commenti qui mi hanno davvero buttato per un loop, perché sono così contrari alla mia prima reazione e quindi in contrasto con l'atteggiamento che ho visto nei miei colleghi. Quindi mi piacerebbe descrivere un approccio alternativo, se non altro per essere la voce dissenziente .

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

Per me, quando sento il cliente dire "Voglio i commenti del 25%", questo è l'inizio di una finestra di dialogo. Per me è chiaro che l'implicazione qui è "Voglio un sacco di testo descrittivo, in modo che i principianti di questa base di codice possano essere subito operativi", non "Voglio aggiungere la casualità in una determinata categoria sintattica" come altre risposte sembra prenderlo E prenderei seriamente questa richiesta, e intendo scrivere molti commenti descrittivi e utili, guidando un nuovo arrivato nella struttura del codice, sottolineando le decisioni ingegneristiche sorprendenti e delineando il ragionamento che ci ha fatto 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 partenza della discussione - cioè prima ancora che iniziamo a parlare. Per me l'implicazione della richiesta è così chiara che non ha nemmeno bisogno di tale chiarimento; ma se per te non è chiaro, dovresti ovviamente controllarli!

Ok, 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 questo sia un serio sforzo aggiuntivo, possibilmente in una seconda fase del progetto, che è al di sopra e al di là della produzione dello strumento a cui si preoccupano di lavorare. Potrebbero essere diversi minuti di discussione per discutere di questo processo e perché è un lavoro aggiuntivo, ma ho intenzione di ometterlo qui perché, come programmatore professionista, mi aspetto che sappia quanto sia difficile fare del bene commenti.
  2. "Un serio sforzo supplementare" significa che potremmo aver bisogno di un budget più lungo e di un budget monetario maggiore; o potremmo aver bisogno di ridurre il budget delle funzionalità; o potremmo dover scendere a compromessi sulla qualità e quantità dei commenti. Questa parte sarà un po 'una negoziazione. Ma secondo me, dovresti essere molto onesto riguardo ai costi di 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 ulteriore tempo e denaro e ottengono commenti di alta qualità. Tutti vincono. E se risulta che la funzione di commento non è così importante per loro che sono disposti a perdere la capacità di flanettare i widget o di lasciare che la scadenza scivoli fino a tardi Granuary, 20x6, allora tutti vincono ancora: ottengono il prodotto vuoi e non devi dedicare lo sforzo extra necessario per creare commenti di alta qualità.

Qui è dove penso che la finestra di dialogo dovrebbe non andare:

  1. Non minacciare il cliente con commenti di bassa qualità. Lascia che ti aiutino a scegliere il livello di impegno che vogliono speso e che sono disposti a pagare. Non promettere loro commenti del 25% e poi informarli che intendi mantenere questa promessa autogenerando casualità dopo che il progetto è stato realizzato.
  2. Non nascondere i tuoi piani. Non promettere loro commenti del 25% e quindi generare automaticamente la casualità senza dire loro che è quello che farai. Quando notano (non se), entrambi perdono tempo: non sono contenti del prodotto che hanno ottenuto e il passaparola è negativo.
  3. Non cercare di convincerli che non vogliono commenti. Vogliono chiaramente commenti. Discutere i compromessi dei vari approcci: sì! Discutere su modi alternativi per rendere il codice base nuovo principiante: sì! Dì loro che non sanno cosa vogliono: eh, no. Vuoi lavorare con loro per ottenere ciò che vogliono; quindi comprendi cosa è e trova il modo migliore per consegnarlo a loro in un budget che approveranno, dando la priorità alle funzionalità a cui si preoccupano di più se le risorse che hanno sono insufficienti.
  4. Non fare scuse su quanto siano difficili da scrivere i commenti. 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 si preoccupano, vale a dire come lo sforzo extra richiesto li colpisce.
risposta data 06.03.2018 - 14:48
fonte
83

Il cliente è il re. Quindi, come imprenditore, devi soddisfare qualsiasi cosa il cliente abbia definito come standard di qualità. O rischi di essere fuori.

Detto questo, è importante sapere come vengono definiti gli standard di qualità (qui poveri):

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

  • Standard di qualità aziendale formale: anche se funziona perfettamente, il codice non conforme verrà considerato di scarsa qualità da così tante persone, che diventerai vecchio prima di convertirli tutti in una pratica migliore. Peggio: strumenti ben noti possono essere utilizzati per automatizzare e legittimare tali parametri di qualità (ad esempio cubo del sonar ). Quasi nessuna scelta.

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

In quest'ultimo caso, potrebbe esserci un po 'di flessibilità, e potresti provare a esprimere il punto in modo diplomatico. 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 nel codice).
  • Problema di accuratezza: se le modifiche vengono eseguite nel codice, devono essere eseguite nei commenti oppure i commenti potrebbero diventare inutili.
  • Problema di refactoring: poiché lo strumento di refactoring non elabora i nomi delle variabili nei commenti.
  • Rischio: l'ambiguità (o l'obsolescenza) dei commenti potrebbe generare confusione e rischiare di aumentare i bug.
  • La quantità non è di qualità
  • Questa divertente raccolta di commenti inutili su StackOverflow .
  • Questo articolo che sostiene che un alto livello di commenti potrebbe persino essere il segno di un odore di codice.

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

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

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

    
risposta data 06.03.2018 - 00:01
fonte
18

The client wants at least 25% of comments in each of its software projects.

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

IMHO, il cliente sa quello che vuole, ma non quello di cui ha bisogno. Dal momento che un cliente non è uno sviluppatore e riceve feedback dai suoi dipendenti / clienti, il tuo cliente vede solo la parte superiore dell'iceberg.

Immagino che il tuo cliente abbia qualche pseudo-conoscenza e vuole che il codice sia ben documentato e 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. Mostra questo se necessario e usalo come immagine per le tue parole.

Parla con il tuo cliente / supervisore / qualsiasi cosa e prova a dire loro i moderni principi del controllo della versione (non c'è bisogno di commenti all'inizio del file) e codice pulito (ti consiglio il libro ) e quindi il conseguente codice auto esplicativo.

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

    
risposta data 06.03.2018 - 08:53
fonte
12

Questo mi ricorda quelle stupide risposte di Overflow dello stack che vedi che consistono in una riga seguita da, letteralmente, "un testo qui per raggiungere il limite minimo di caratteri".

Quando ciò accade, si potrebbero argomentare che due gruppi di persone sono in errore:

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

  2. Le persone che hanno fornito informazioni che non erano formate correttamente, quindi hanno aggiunto rumore artificiale quando il sistema ha richiesto loro di aggiungere altra sostanza effettiva

A volte, una domanda sarà sia semplice che sull'argomento, e non c'è molto altro da dire che poche parole. Tuttavia, questo è estremamente raro. In quasi tutti i casi, c'è molto più sostanza da dire. Se non altro, dovrebbe essere accecantemente ovvio che il modo per aggirare una restrizione di caratteri non è semplicemente scaricare del rumore casuale nel tuo post.

Questa situazione di commenti che stai affrontando è quasi la stessa. I tuoi sviluppatori hanno inoltrato una richiesta di commenti e l'hanno implementata scaricando il rumore casuale nel loro codice. Documentando i nomi delle variabili, proprio accanto alla dichiarazione delle variabili, è vandalismo . Questo non dovrebbe mai essere successo.

"Ma in quale altro modo possiamo arrivare al 25%?" Scrivendo commenti reali di sostanza. Usa più parole, parole migliori, le parole migliori per documentare l'effetto delle funzioni. Espandi le tue spiegazioni. Descrivi i casi limite in modo più dettagliato.

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

    
risposta data 06.03.2018 - 15:08
fonte
5

Non so quale sia il problema con questo requisito.

Proprio per la semplice ossigenazione del tuo codice probabilmente sei già al 10% circa. E prendiamo un altro 5% di 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 si aggira intorno al 15% (si si, lo so, il 5% del 90% è inferiore al 5%, non è nitpick). Se il tuo doxygen è inferiore al 10%, forse i tuoi metodi sono molto lunghi; di solito è una buona idea scomporle in quelle più piccole (per lo più private / protette) o usare classi di helper più generiche ecc.

Ora, per il resto del testo dei commenti, inserire considerazioni sulla progettazione e scenari di utilizzo in commenti a livello di classe / file. Avere alcune tabelle o ASCII-art (o codice doxygen che genera cose dall'aspetto più gradevole quando viene renderizzato). Non so, ovviamente, di cosa tratta il tuo progetto, ma credo che tu possa farlo senza commenti fittizi (oltre alla piastra di doxygenation) e arrivare a qualcosa di simile 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 con esso. Ad ogni modo, parla con loro per discutere di ciò che dovrebbero includere i commenti; e mostra loro un esempio di file commentato per vedere se sono contenti. Se sono così, è così, se pensano che manchi qualcosa ti diranno cosa manca. Non ti diranno "Non possiamo suggerire alcun commento extra, ma vogliamo comunque che tu aggiunga alcuni".

PS - Guarda il codice dei contenitori Java standard per vedere come puoi raggiungere, oh, il 70% circa ...

    
risposta data 06.03.2018 - 19:26
fonte
5

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

    
risposta data 06.03.2018 - 20:33
fonte
4

Sappiamo tutti che questo è un requisito da schifo. La domanda interessante qui è

how to react?

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

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

Solo una volta che chiedono perché insegnerò loro che il punto di buon nome è di evitare la necessità di commentare.

In alternativa, proporrò la creazione di documentazione finalizzata a far sì che un programmatore di manutenzione con un insieme definito di qualifiche supposte sia in grado di accelerare le idee alla base del progetto. O certo, potrei darti un 25% di commenti. Fino a voi.

    
risposta data 06.03.2018 - 16:40
fonte
3

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

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

E io dico a me stesso, così CHE è un segno più significa !! Wow, grazie per avermelo detto, non lo sapevo.

Ma detto questo, il cliente paga il conto. Pertanto, dai loro ciò che vogliono. Se lavorassi in un concessionario di auto e un cliente dicesse che voleva un furgone, non avrei discusso con lui se avesse davvero bisogno di un camioncino e lo interrogasse su cosa si aspettasse di trascinare in esso. Gli venderei un furgoncino.

Ok, ci sono momenti in cui ciò che i clienti dicono di volere e ciò di cui ha veramente bisogno sono così distanti che cerco di discutere la questione con lui, forse 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 torna più tardi e dice, Oh, questo in realtà non ha soddisfatto i miei requisiti di business, quindi possiamo caricarlo di più per fare ciò che gli abbiamo detto di fare la prima volta. Quanto puoi negoziare con il cliente dipende da quanto si fidi della tua esperienza, dal modo in cui il loro contratto con te si adatta all'organizzazione e, francamente, da come sono diventati teste di toro.

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

Tieni presente che le persone con cui la tua azienda sta negoziando potrebbero o meno essere quelle che hanno inventato questa regola del 25%. Potrebbe essere una regola imposta su di loro da più in alto.

Vedo cinque possibili risposte:

Uno. Convinci il tuo capo o chiunque stia negoziando con il cliente per discuterne. Le probabilità sono che questo non porterà a nulla, ma puoi provare.

Due. Rifiuta di farlo. Questo probabilmente ti farà licenziare, o se la compagnia è d'accordo con te, farai 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 dei blocchi di commento davanti a tutte le funzioni che elencavano 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é devi tenerli aggiornati non è valida. Non è necessario tenerli aggiornati perché nessun programmatore serio li guarderà mai. Se c'è qualche domanda al 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 stai per aggiungere commenti inutili ridondanti, forse vale la pena dedicare del tempo a scrivere un programma per generarli. Qualcosa di un investimento in anticipo, ma potrebbe salvare un sacco di digitazione lungo la strada.

Quando ho iniziato a lavorare in questo settore, una società per la quale ho lavorato utilizzava un programma pubblicizzato come "Scrive la documentazione per te! Completa documentazione per ogni programma!" Il sistema richiedeva di dare a tutte le variabili nomi sostanzialmente privi di significato e quindi di avere una tabella che fornisse un nome significativo per ogni variabile, quindi in sostanza ciò che faceva la "documentazione automatica" era sostituire il nome senza significato che ci obbligava a usare con un nome significativo. Ad esempio, questo ha funzionato con COBOL: nel tuo programma avresti una riga che diceva

MOVE IA010 TO WS124

e avrebbero generato una riga 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 una documentazione altrettanto inutile abbastanza facilmente. Leggi una riga come

a=b+c

e genera il commento

// add b to c and save result in a

Ecc.

Five. Sfruttare al meglio la 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 disse che stavano per iniziare a misurare la produttività dei programmatori di quante linee di codice producevamo a settimana. Quando ci è stato detto durante un incontro, ho detto, fantastico! Posso facilmente aumentare il mio punteggio. Basta scrivere

x=x+4;

Invece scriverò:

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

Loops? Scordatelo, copierò e incollerò il codice dieci volte. Ecc.

Quindi, se stanno andando a contare le righe di commenti, riduci ogni riga e continua l'idea nella riga successiva. Se c'è una modifica a ciò che accade nei commenti, non aggiornare il commento esistente. Metti una data su di esso, quindi copia l'intero testo e scrivi "Aggiornato" e una nuova data. Se il cliente lo interroga, dì che hai pensato che fosse necessario mantenere la cronologia. Ecc ecc.

    
risposta data 06.03.2018 - 17:25
fonte
2

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

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

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

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

    
risposta data 06.03.2018 - 15:05
fonte
2

Nel breve termine non c'è nulla che tu possa veramente fare. Vai insieme.

Dovresti anche ignorare tutte le idee stupide che sto vedendo in questo thread sulle proteste passive aggressive e gli scherzi sciocchi all'interno del codice.

Una volta che hai sviluppato una relazione di fiducia con il cliente, saranno in una posizione migliore per ascoltare i tuoi ragionamenti. Potresti scoprire che questa è una domanda sciocca da parte di una persona che è stata una volta influente e che ha scarso supporto in -house.

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

    
risposta data 06.03.2018 - 21:00
fonte
2

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

Mi sembra che il cliente abbia fatto qualche ricerca. Potrebbe aver letto da qualche parte che il codice di qualità contiene in genere circa il 25% dei commenti. Ovviamente si preoccupa / si preoccupa per la manutenzione più avanti lungo la strada. Ora, come fa a renderlo concreto in un documento sui requisiti che deve essere legato a un contratto? Non è facile Potrebbe anche essere impossibile. Eppure vuole assicurarsi che otterrà un valore per i suoi soldi, così enumera alcuni indicatori di qualità.

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

Se sei seriamente interessato a documentare il tuo codice e a fornire il contesto per la banda di manutenzione, questo requisito verrà soddisfatto automaticamente. Quindi non essere una figa!

Alla fine, che si tratti del 21% o del 29%, a nessuno importa. Il client avrà il tuo materiale recensito da uno sviluppatore indipendente e lui capirebbe meglio cosa hai fatto.

    
risposta data 06.03.2018 - 22:57
fonte
0

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

Per loro tutto ciò che sanno, è conosciuto da tutti.

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

Con questo standard puoi costringere le persone a entrare in una routine di scrivere commenti.

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

Avere commenti alle righe con bug non ovvi può anche aiutare a evitare che futuri programmatori interrompano completamente un programma per errore (specialmente quando la parte "in fase di interruzione" non è ovvia quando si esegue un test rapido).

    
risposta data 07.03.2018 - 01:26
fonte