È considerata una pratica scorretta includere un numero di bug nel nome di un metodo per una soluzione temporanea?

Il mio collega che è un ragazzo anziano mi sta bloccando su una revisione del codice perché vuole che io chiami un metodo "PerformSqlClient216147Workaround" perché è una soluzione alternativa per qualche difetto ###. Ora, la mia proposta di nome del metodo è qualcosa come PerformRightExpressionCast che tende a descrivere ciò che il metodo effettivamente fa. I suoi argomenti vanno sulla falsariga di: "Bene, questo metodo è usato solo come soluzione alternativa per questo caso e da nessun'altra parte".

Includere il numero di bug all'interno del nome del metodo per una soluzione temporanea sarebbe considerato una cattiva pratica?

Non vorrei nominare il metodo come suggerito dal tuo collega. Il nome del metodo dovrebbe indicare cosa fa il metodo. Un nome come PerformSqlClient216147Workaroundnon indica cosa fa. Se non altro, utilizzare i commenti che descrivono il metodo per indicare che si tratta di una soluzione alternativa. Questo potrebbe apparire come il seguente:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

Concordo con MainMa sul fatto che i numeri di bug / difetto non dovrebbero apparire nel codice sorgente stesso ma piuttosto nei commenti sul controllo del codice sorgente in quanto si tratta di metadati, ma non è terribile se compaiono nei commenti sul codice sorgente. I numeri di bug / difetto non dovrebbero mai essere usati nei nomi dei metodi.

Niente è più permanente di una correzione temporanea che funziona.

Il suo suggerimento sembra buono tra 10 anni? In passato era pratica comune commentare ogni modifica con il difetto corretto. Più di recente (come gli ultimi 3 decenni), questo commento di stile è ampiamente accettato come riduzione della manutenibilità del codice - e cioè con semplici commenti, non con nomi di metodi.

Ciò che propone sono prove convincenti che i sistemi di controllo qualità e controllo qualità sono significativamente carenti. Il rilevamento di difetti e correzioni di errori appartiene al sistema di rilevamento dei difetti, non al codice sorgente. La traccia delle modifiche al codice sorgente appartiene al sistema di controllo del codice sorgente. Il riferimento incrociato tra questi sistemi consente di tracciare i difetti nel codice sorgente .....

Il codice sorgente è lì per oggi, non ieri e non domani (come in, non si digita in sorgente cosa si intende fare l'anno prossimo) ...

Quindi è una soluzione temporanea? Quindi utilizzare il nome suggerito dal revisore, ma contrassegnare il metodo come obsoleto, in modo che utilizzarlo genererebbe un avviso ogni volta che qualcuno sta compilando il codice.

In caso contrario, potresti sempre dire che 216147non ha senso nel codice, poiché il codice non è collegato al sistema di tracciamento dei bug (è piuttosto il sistema di tracciamento dei bug che è collegato al controllo del codice sorgente). Il codice sorgente non è un buon posto per riferimenti a ticket e versioni di bug, e se hai davvero bisogno di inserire quei riferimenti lì, fallo nei commenti.

Si noti che anche nei commenti, il numero di bug da solo non è molto prezioso. Immagina il seguente commento:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Immagina che il codice sia stato scritto dieci anni fa, che ti sei appena unito al progetto e che quando hai chiesto dove potevi trovare informazioni sul bug 8247, i tuoi colleghi hanno detto che c'era un elenco di bug sul sito web del software di sistema di segnalazione, ma il sito Web è stato rifatto cinque anni fa e il nuovo elenco di bug ha numeri diversi.

Conclusione: non hai idea di cosa sia questo bug.

Lo stesso codice avrebbe potuto essere scritto in un modo leggermente diverso:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Ora hai una visione chiara del problema. Anche se sembra che il collegamento ipertestuale alla fine del commento sia morto cinque anni fa, non importa, dal momento che puoi ancora capire perché è FindReportsByDatestato sostituito FindReportsByDateOnly.

Trovo PerformSqlClient216147Workaroundpiù informativo quindi PerformRightExpressionCast. Non vi è alcun dubbio nel nome della funzione su ciò che fa, perché lo fa o come ottenere maggiori informazioni al riguardo. È una funzione esplicita che sarà semplicissima da cercare nel codice sorgente.

Con un sistema di tracciamento dei bug tale numero identifica in modo univoco il problema e quando si risolve quel bug nel sistema fornisce tutti i dettagli necessari. Questa è una cosa molto intelligente da fare nel codice sorgente e farà risparmiare tempo ai futuri sviluppatori quando cercherà di capire perché è stata apportata una modifica.

Se vedi molti di questi nomi di funzioni se il tuo codice sorgente, il problema non è la convenzione di denominazione. Il problema è che hai un software difettoso.

C'è valore nel suggerimento del tuo collega; fornisce la tracciabilità associando le modifiche al codice con il motivo, documentato nel database dei bug con quel numero di ticket, perché la modifica è stata effettuata.

Tuttavia, suggerisce anche che l'unica ragione per cui esiste la funzione è aggirare il bug. Che, se il problema non fosse un problema, non vorresti che il software facesse quella cosa. Presumibilmente si fa desiderare il software per fare la sua cosa, in modo che il nome della funzione dovrebbe spiegare che cosa fa e perché il dominio del problema richiede che sia fatta; non perché il database dei bug ne abbia bisogno. La soluzione dovrebbe apparire come parte dell'applicazione, non come un cerotto.

Penso che sia tu che lui abbiamo ottenuto tutto sproporzionato.

Sono d'accordo con il tuo argomento tecnico, ma alla fine della giornata non farà molta differenza, soprattutto se si tratta di una correzione temporanea che può essere rimossa dalla base di codice in pochi giorni / settimane / mesi.

Penso che dovresti rimettere il tuo ego nella sua scatola e lasciargli fare a modo suo. (Se anche lui stesse ascoltando, direi che dovete scendere a compromessi. Entrambi gli ego tornano nelle loro scatole.)

Ad ogni modo, tu e lui abbiamo cose migliori da fare.

Includere il numero di bug all'interno del nome del metodo per una soluzione temporanea sarebbe considerato una cattiva pratica?

Sì.

Idealmente, la tua classe dovrebbe mappare al meglio / implementare un concetto nel flusso / stato dell'applicazione. I nomi delle API di questa classe dovrebbero riflettere ciò che fanno allo stato della classe, in modo che il codice client possa facilmente utilizzare quella classe (cioè non specificare un nome che letteralmente non significhi nulla a meno che tu non lo legga specificamente).

Se una parte dell'API pubblica di quella classe dice sostanzialmente "esegui l'operazione Y descritta nel documento / posizione X", la capacità di altre persone di comprendere l'API dipenderà da:

1. sapendo cosa cercare nella documentazione esterna

2. sapendo dove cercare la documentazione esterna

3. loro prendono il tempo e lo sforzo e guardano davvero.

Inoltre, il nome del metodo non menziona nemmeno dove si trova "posizione X" per questo difetto.

Presuppone (per nessun motivo realistico) che chiunque abbia accesso al codice, abbia anche accesso al sistema di localizzazione dei difetti e che il sistema di localizzazione rimarrà attivo fino a quando rimarrà il codice stabile.

Per lo meno, se sai che il difetto sarà sempre accessibile nella stessa posizione e questo non cambierà (come un numero di difetto Microsoft che è stato allo stesso URL negli ultimi 15 anni), dovresti fornire un link al problema nella documentazione dell'API.

Tuttavia, potrebbero esserci soluzioni alternative per altri difetti, che interessano più dell'API di una classe. Cosa farai allora?

Avere API con lo stesso numero di difetto in più classi ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);non ti dice molto e rende il codice più oscuro.

Potresti decidere che tutti gli altri difetti vengono risolti usando nomi descrittivi dell'operazione ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);), tranne nel caso del tuo difetto 216147 (che infrange il principio di progettazione di "meno sorpresa" - o se vuoi metterlo in quel modo, esso aumenta la misurazione di "WTFs / LOC" del codice).

TL; DR: cattiva pratica! Vai nella tua stanza!

Gli obiettivi principali di un programmatore dovrebbero essere il codice di lavoro e la chiarezza di espressione.

Denominazione di un metodo di soluzione alternativa (.... Soluzione alternativa). Sembrerebbe raggiungere questo obiettivo. Si spera che a un certo punto il problema sottostante venga risolto e il metodo di soluzione alternativa rimosso.

Per me, nominare un metodo dopo un bug suggerisce che il bug non è stato risolto o che la causa principale non è stata identificata. In altre parole, suggerisce che c'è ancora uno sconosciuto. Se stai risolvendo un bug in un sistema di terze parti, la soluzione alternativa è una soluzione perché conosci la causa: semplicemente non possono risolverla.

Se una parte dell'interazione con SqlClient richiede l'esecuzione di un cast di espressioni corrette, il codice dovrebbe essere "performRightExpressionCast ()". Puoi sempre commentare il codice per spiegare il perché.

Ho passato gli ultimi 4 anni e mezzo a mantenere il software. Una delle cose che rende il codice confuso da capire quando si entra è il codice che è scritto nel modo in cui è solo dovuto alla storia. In altre parole, non è così che funzionerebbe se fosse scritto oggi. Non mi riferisco alla qualità, ma a un punto di vista.

Un mio collega una volta disse: "Quando correggi un difetto, rendi il codice come avrebbe dovuto essere". Il modo in cui lo interpreto è "Cambia il codice come sarebbe se questo bug non esistesse mai".

conseguenze:

1. Di solito, di conseguenza meno codice.
2. Codice semplice
3. Meno riferimenti a bug nel codice sorgente
4. Meno rischi di regressione futura (una volta che la modifica del codice è stata completamente verificata)
5. Più facile da analizzare perché gli sviluppatori non devono caricarsi della storia dell'apprendimento che non è più pertinente.

Il codice sorgente non ha bisogno di dirmi come è arrivato al suo stato attuale. Il controllo della versione può dirmi la storia. Ho bisogno che il codice sorgente sia semplicemente nello stato necessario per funzionare. Detto questo, un commento occasionale "// bug 12345" non è una cattiva idea, ma viene abusato.

Quindi, quando decidi se nominare o meno il tuo metodo "PerformSqlClient216147Workaround", poniti queste domande:

1. Se avessi saputo del bug 216147 prima di scrivere il codice, come lo avrei gestito?
2. Qual è la soluzione alternativa? Se qualcuno che non avesse mai visto questo codice prima di guardarlo, sarebbe in grado di seguirlo? Il controllo del sistema di tracciamento dei bug è necessario per sapere come funziona questo codice?
3. Quanto è temporaneo questo codice? Nella mia esperienza, le soluzioni temporanee di solito diventano permanenti, come indica @mattnz.