La diffusion de code avec des commentaires de refactorisation est-elle une bonne idée?

Je travaille sur un projet "spaghetti-code", et pendant que je corrige des bugs et implémente de nouvelles fonctionnalités, je fais aussi quelques refactoring afin de rendre le code testable à l'unité.

Le code est souvent si étroitement couplé ou compliqué que la correction d'un petit bug entraînerait la réécriture de nombreuses classes. J'ai donc décidé de tracer une ligne quelque part dans le code où j'arrête le refactoring. Pour que cela soit clair, je laisse quelques commentaires dans le code expliquant la situation, comme:

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;
    }
}

Ou, un autre morceau de gâteau:

// 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>>>>();

Est-ce une bonne idée? Que dois-je garder à l'esprit lorsque je le fais?

La diffusion de code avec des commentaires de refactorisation est-elle une bonne idée?

Si vous avez alloué du temps pour terminer votre refactoring, et si vous le faites vraiment, alors oui - cela fonctionnera.

Que dois-je garder à l'esprit lorsque je le fais?

Les IDE modernes ont une option pour trouver et afficher les lignes TODO. Vous devriez les vérifier de temps en temps et essayer de réduire leur nombre chaque fois que vous le pouvez.

Je ferais de telles considérations /// @todopour doxygen ou une balise personnalisée facile à installer pour javadoc , afin qu'elle soit automatiquement extraite dans la section des tâches des documents de l'API. Les commentaires simples seront trop facilement ignorés et finiront par se perdre dans les profondeurs du code.

[Modifier] BTW: est-ce une bonne idée:

pendant que je corrige des bugs et implémente de nouvelles fonctionnalités, je fais aussi du refactoring afin de rendre le code testable à l'unité

Je pense (sachez par expérience!), Le refactoring peut être très dangereux, surtout quand il n'y a toujours pas de tests unitaires. Donc, vous feriez mieux de limiter votre travail supplémentaire (lors de la correction de bogues, etc.) en ajoutant des commentaires à faire ... Nous savons tous: lorsque cela est possible;)