Ist es eine gute Idee, Code mit Refactoring-Kommentaren zu verbreiten?

Ich arbeite an einem "Spaghetti-Code" -Projekt, und während ich Fehler behebe und neue Funktionen implementiere, führe ich auch einige Umgestaltungen durch, um den Code Unit-testbar zu machen.

Der Code ist oft so eng miteinander verbunden oder kompliziert, dass das Beheben eines kleinen Fehlers dazu führen würde, dass viele Klassen neu geschrieben werden. Also habe ich beschlossen, irgendwo im Code eine Linie zu ziehen, an der ich mit dem Refactoring aufhöre. Um dies zu verdeutlichen, füge ich einige Kommentare in den Code ein, die die Situation erklären, wie zum Beispiel:

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

Oder ein weiteres Stück Kuchen:

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

Ist das eine gute Idee? Was muss ich dabei beachten?

refactoring comments

— Uooo
quelle

Verwandte / Duplikate: Sind TODO-Kommentare sinnvoll?

— Mücke

Dies ist ein meinungsbasiertes Thema. Meine persönliche Meinung ist jedoch, dass dies genau die Art von Kommentar ist, die nützlich ist und die ich gerne im Code anderer Leute finden würde: Sie enthält wichtige Informationen, die aus dem Code noch nicht ersichtlich sind. nicht was eine Methode macht, sondern warum .

— Kilian Foth

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

— Margabit

Kommentare, die mir sagen, warum ein Code stinkt, werden unglaublich geschätzt. Ich habe möglicherweise kein Verständnis für die Codebasis, daher werde ich nur ein Problem sehen und "Was zum Teufel?" Denken, aber ein Kommentar, der erklärt, warum es so ist, wie es ist, hilft mir, den Code schneller zu umgehen. Ja, sehr viel. (Vorausgesetzt, Sie können den Code nicht so reparieren, dass er nicht WTF ist!)

— Phoshi

Antworten:

Ist es eine gute Idee, Code mit Refactoring-Kommentaren zu verbreiten?

Wenn Sie Zeit für die Fertigstellung Ihres Refactorings zur Verfügung gestellt haben und wenn Sie es wirklich tun, dann ja - es wird funktionieren.

Was muss ich dabei beachten?

Moderne IDEs haben die Möglichkeit, TODO-Zeilen zu finden und anzuzeigen. Sie sollten sie von Zeit zu Zeit überprüfen und versuchen, ihre Anzahl zu reduzieren, wann immer Sie können.

— BЈовић
quelle

Ich würde solche Überlegungen zu /// @todoKommentaren für doxygen oder zu einem einfach zu installierenden benutzerdefinierten Tag für javadoc machen , damit es automatisch in den Aufgabenbereich der API-Dokumente extrahiert wird. Einfache Kommentare werden zu leicht übersehen und gehen schließlich in den Tiefen des Codes verloren.

[Bearbeiten] Übrigens: Ist das eine gute Idee:

Während ich Fehler behebe und neue Funktionen implementiere, führe ich auch einige Umgestaltungen durch, um den Code einheitlich testbar zu machen

Ich denke (aus Erfahrung wissen!), Refactoring kann sehr gefährlich sein, besonders wenn es noch keine Unit-Tests gibt. Sie sollten also Ihre zusätzliche Arbeit (beim Beheben von Fehlern usw.) auf das Hinzufügen von Aufgabenkommentaren beschränken ... Wir alle wissen: wann immer möglich;)

— Wolf
quelle

Code-Snippet in der Frage lautet wie Java. Warum empfehlen Sie Doxygen?

— Mücke

Ich wusste, dass doxygen @todo unterstützt - für javadoc war ich mir nicht sicher - aber ist die Sprache wirklich so wichtig? Aus meiner Sicht hat das Java-Beispiel ein tieferes Problem veranschaulicht.

— Wolf

@gnat: Denkst du, es ist jetzt besser?

— Wolf