Czy rozpowszechnianie kodu z refaktoryzacją komentarzy to dobry pomysł?

Pracuję nad projektem „kodu spaghetti” i podczas gdy naprawiam błędy i wdrażam nowe funkcje, robię też pewne refaktoryzacje, aby kod mógł być testowany jednostkowo.

Kod jest często tak ściśle powiązany lub skomplikowany, że naprawienie małego błędu spowodowałoby przepisanie wielu klas. Postanowiłem więc narysować linię w kodzie, w której przestaję refaktoryzować. Aby to wyjaśnić, umieszczam w kodzie kilka komentarzy wyjaśniających sytuację, takich jak:

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

Lub kolejny kawałek ciasta:

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

Czy to dobry pomysł? O czym powinienem pamiętać?

Czy rozpowszechnianie kodu z refaktoryzacją komentarzy to dobry pomysł?

Jeśli poświęciłeś czas na zakończenie refaktoryzacji, a jeśli naprawdę to robisz, to tak - to się uda.

O czym powinienem pamiętać?

Nowoczesne IDE mają opcję wyszukiwania i pokazywania linii do zrobienia. Powinieneś je od czasu do czasu sprawdzać i starać się zmniejszać ich liczbę, kiedy tylko możesz.

Chciałbym zrobić takie uwagi /// @todokomentarze doxygen lub łatwego do zainstalowania niestandardowego tagu dla javadoc , więc zostanie on automatycznie wyodrębniony do sekcji todo w dokumentach API. Zwykłe komentarze zostaną zbyt łatwo przeoczone i ostatecznie zgubią się w głębi kodu.

[Edytuj] BTW: czy to dobry pomysł:

podczas gdy naprawiam błędy i wdrażam nowe funkcje, dokonuję również refaktoryzacji, aby kod mógł być testowany jednostkowo

Myślę (wiem z doświadczenia!), Że refaktoryzacja może być bardzo niebezpieczna, szczególnie gdy wciąż nie ma testów jednostkowych. Więc lepiej ogranicz swoją dodatkową pracę (przy naprawianiu błędów itp.) W dodawaniu komentarzy do zrobienia ... Wszyscy wiemy: kiedy to możliwe;)