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


11

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?



3
Il s'agit d'un sujet basé sur l'opinion; mais mon opinion personnelle est que c'est exactement le type de commentaire qui est utile, et que je souhaiterais trouver dans le code des autres: il vous indique des informations importantes qui ne sont pas déjà évidentes dans le code; pas ce qu'une méthode fait, mais pourquoi .
Kilian Foth

2
HashMap <String, Map <String, Map <String, List <String> >>>: o
margabit

5
Les commentaires qui me disent pourquoi un morceau de code semble malodorant sont extrêmement appréciés. Je ne comprends peut-être pas la base de code, donc je vais juste voir un problème et penser "What the fuck?", Mais un commentaire expliquant pourquoi il est tel qu'il m'aidera à contourner le code plus rapidement. Oui, faites-le beaucoup. (En supposant que vous ne pouvez pas corriger le code pour qu'il ne soit pas WTF, bien sûr!)
Phoshi

Réponses:


13

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.


2

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


extrait de code dans la question se lit comme Java, pourquoi recommandez-vous Doxygen?
moucher

Je savais que doxygen prend en charge @todo - pour javadoc, je n'en étais pas sûr - mais la langue est-elle vraiment si importante? De mon point de vue, l'exemple java a illustré un problème plus profond.
Wolf

1
@gnat: Pensez-vous que c'est mieux maintenant?
Wolf
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.