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


11

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ć?


1
powiązane / zduplikowane: czy komentarze TODO mają sens?
komara

3
Jest to temat oparty na opiniach; ale moja osobista opinia jest taka, że ​​jest to dokładnie taki rodzaj komentarza, który jest użyteczny i że chciałbym znaleźć go w kodzie innych osób: zawiera ważne informacje, które nie są już oczywiste z kodu; nie to, co robi metoda, ale dlaczego .
Kilian Foth,

2
HashMap <Ciąg, Mapa <Ciąg, Mapa <Ciąg, Lista <String> >>>: o
margabit,

5
Komentarze, które mówią mi, dlaczego kawałek kodu wygląda śmierdząco, są niezwykle mile widziane. Być może nie rozumiem bazy kodu, więc po prostu zobaczę problem i pomyślę „Co do cholery?”, Ale komentarz wyjaśniający, dlaczego tak jest, pomoże mi szybciej obejść kod. Tak, bardzo to zrób. (Zakładając, że nie możesz naprawić kodu, aby nie był WTF, oczywiście!)
Phoshi,

Odpowiedzi:


13

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.


2

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


fragment kodu w pytaniu brzmi jak Java, dlaczego polecasz Doxygen?
komara

Wiedziałem, że doxygen obsługuje @todo - dla javadoc nie byłem pewien - ale czy język jest tak ważny? Z mojego punktu widzenia przykład java ilustruje głębszy problem.
Wolf

1
@gnat: Czy uważasz, że teraz jest lepiej?
Wolf
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.