La diffusione del codice con i commenti di refactoring è una buona idea?

Sto lavorando a un progetto "spaghetti-code" e, mentre correggo i bug e implemento nuove funzionalità, faccio anche un po 'di refactoring per rendere il codice testabile.

Il codice è spesso così strettamente accoppiato o complicato che la correzione di un piccolo bug comporterebbe la riscrittura di molte classi. Così ho deciso di tracciare una linea da qualche parte nel codice in cui smetto di refactoring. Per chiarire questo, lascio cadere alcuni commenti nel codice che spiegano la situazione, come:

class RefactoredClass {
    private SingletonClass xyz;

    // I know SingletonClass is a Singleton, so I would not need to pass it here.
    // However, I would like to get rid of it in the future, so it is passed as a
    // parameter here to make this change easier later.
    public RefactoredClass(SingletonClass xyz) {
        this.xyz = xyz;
    }
}

Oppure, un altro pezzo di torta:

// This might be a good candidate to be refactored. The structure is like:
// Version String
//    |
//    +--> ...
//    |
//    +--> ...
//          |
//    ... and so on ...    
//
Map map = new HashMap<String, Map<String, Map<String, List<String>>>>();

E 'questa una buona idea? Cosa devo tenere a mente quando lo faccio?

refactoring comments

— Uooo
fonte

correlati / duplicati: i commenti TODO hanno senso?

— moscerino il

Questo è un argomento basato sull'opinione; ma la mia opinione personale è che questo è esattamente il tipo di commento che è utile e che vorrei trovare nel codice di altre persone: ti dice informazioni importanti che non sono già evidenti dal codice; non quello che fa un metodo, ma perché .

— Kilian Foth,

HashMap <String, Map <String, Map <String, List <String>

— >>>

I commenti che mi dicono perché un pezzo di codice appare maleodorante sono incredibilmente enormemente apprezzati. Potrei non avere la tua comprensione della base di codice, quindi vedrò un problema e penserò "Che cazzo?", Ma un commento che spiega perché è così mi aiuterà a aggirare il codice più velocemente. Sì, molto. (Supponendo che non sia possibile correggere il codice in modo che non sia WTF, ovviamente!)

— Phoshi,

Risposte:

La diffusione del codice con i commenti di refactoring è una buona idea?

Se hai assegnato del tempo per terminare il refactoring e se lo fai davvero, allora sì - funzionerà.

Cosa devo tenere a mente quando lo faccio?

Gli IDE moderni hanno un'opzione per trovare e mostrare le linee TODO. Dovresti controllarli di volta in volta e cercare di ridurne il numero ogni volta che puoi.

— BЈовић
fonte

Vorrei fare /// @todocommenti su tali considerazioni per doxygen o un tag personalizzato facile da installare per javadoc , quindi viene automaticamente estratto nella sezione todo dei documenti API. I commenti semplici verranno trascurati troppo facilmente e alla fine andranno persi nelle profondità del codice.

[Modifica] A proposito: è una buona idea:

mentre sto correggendo i bug e implementando nuove funzionalità, faccio anche un po 'di refactoring per rendere il codice testabile in unità

Penso (per esperienza!), Il refactoring può essere molto pericoloso, soprattutto quando non ci sono ancora test unitari. Quindi è meglio limitare il lavoro extra (quando si correggono i bug ecc.) Sull'aggiunta di todo commenti ... Sappiamo tutti: quando possibile;)

— Lupo
fonte

snippet di codice nella domanda legge come Java, perché mi consiglia Doxygen?

— moscerino

Sapevo che doxygen supporta @todo - per javadoc non ero sicuro - ma la lingua è davvero così importante? Dal mio punto di vista, l'esempio java ha illustrato un problema più profondo.

— Lupo,

@gnat: pensi che sia meglio adesso?

— Lupo,