Dlaczego źle jest komentować kod, a następnie stopniowo go usuwać, aby śledzić to, co już zrobiłem i co pozostało do zrobienia?

Ilekroć dowiaduję się, że duża część mojego kodu musi zostać zmieniona, albo dlatego, że jest niepoprawna, albo dlatego, że musi zostać dostosowana do poważnych zmian architektonicznych spowodowanych innymi przyczynami, zazwyczaj tak robię:

1. Komentuję cały kod, który, jak podejrzewam, może będę musiał zmienić. Skomentowany kod traktuję jako rodzaj mojej listy TODO.
2. Stopniowo przeglądam skomentowany kod i odkomentuję części tego kodu, lub kopiuję i wklejam go w innym miejscu, a następnie edytuję je w razie potrzeby lub przepisuję części tego kodu od zera, patrząc na skomentowany kod w celach informacyjnych. Ilekroć myślę, że skończyłem z częścią skomentowanego kodu, usuwam go.
3. Kontynuuję to, dopóki nie zobaczę więcej skomentowanego kodu.

Powinienem zauważyć, że w dużej mierze robię to w ramach osobistego projektu, który rozwijam sam.

Powiedziano mi jednak, że powinienem przestać to robić. Powiedziano mi, że zamiast tego powinienem zacząć używać git, odwołując się do starych commits, aby zobaczyć stary kod, zamiast pozostawiać kod z komentarzem. Powiedziano mi:

Komentowanie kodu to zły nawyk, który należy usunąć. Brakuje Ci doświadczenia, więc tego nie rozumiesz. Jeśli za kilka lat zobaczysz kod innej osoby, która lubi komentować kod, sam zaczniesz przeklinać tę osobę. Ilekroć widzę skomentowany kod, usuwam go w całości, nawet na niego nie patrząc, ponieważ zwykle taki kod jest całkowicie bezwartościowy. Z pewnością nie dostrzeżesz wad komentowania kodu w małych, jednoosobowych projektach; ale jeśli znajdziesz pracę i utrzymasz ten nawyk, będzie to wstyd.

Czy mogę zapytać, jakie są wady tego, co robię, czego teraz nie widzę?

Muszę powiedzieć, że tak naprawdę nie lubię tylko używać git, aby zobaczyć poprzedni kod. Jak powiedziałem, komentowanie kodu traktuję jako rodzaj listy rzeczy do zrobienia; podczas gdy git pokaże mi, jak kiedyś wyglądał kod, nie powie jasno, które części kodu należy jeszcze przejrzeć, a które już wykonano. Obawiam się, że mogę przegapić część kodu i wprowadzić błędy.

Dla kompletności uważam, że powinienem dodać, że osoba, którą cytuję, jest doświadczonym programistą i fanem „Clean Code” wuja Boba - a wujek Bob surowo skrytykował skomentowanie kodu w swojej książce.

Jeśli ostatecznie usuniesz cały skomentowany kod, nie widzę w tym prawdziwego problemu. Pozostawienie skomentowanego kodu w bazie kodu jest złą praktyką, ale nie to robisz, jeśli przejdziesz przez to wszystko i go wyeliminujesz. Podejrzewam, że osoba, z którą rozmawiasz, nie rozumie procesu, którego używasz, lub jest dogmatyczna.

W rzeczywistości skomentowany kod jest nieszkodliwy. Problem polega na tym, że jest nieuporządkowany i utrudnia czytanie. Są o wiele gorsze grzechy, ale ich usunięcie jest bardzo proste. Jako osoba, która skomentowała kod, jesteś w najlepszej sytuacji, aby ustalić, że można go całkowicie usunąć.

Wiele IDE i edytorów kodu rozumie jakąś składnię „TODO” w komentarzach. Jest to alternatywny sposób oznaczania, co należy zmienić. Możesz to rozważyć, ponieważ daje trochę więcej informacji o tym, co myślałeś, kiedy to zaznaczyłeś.

Pod koniec dnia postępuj w taki sposób, aby uzyskać najlepszy wynik. Nawet jeśli byłby to projekt zespołowy, dopóki usuniesz cały skomentowany kod, nie obciążasz nikogo innego.

Czy mogę zapytać, jakie są wady tego, co robię, czego teraz nie widzę?

Prawdopodobnie żaden, jeśli pracujesz sam i nie używasz kontroli wersji i uważasz, że możesz to zrobić w ten sposób.

W rzeczywistości bez kontroli wersji nie ma większego znaczenia, co robisz w dowolnym momencie „czasu”, ponieważ kod jest zawsze tym, co bieżący plik jest „zapisywany”, jak w systemie operacyjnym.

Jeśli korzystasz z kontroli wersji i masz mnóstwo komentarzy jako „listy rzeczy do zrobienia”, a niektóre naprawisz i usuniesz komentarz, a następnie powtórz, powtórz itp., Wówczas kod i komentarze zostaną zapisane w historii zmian. Nie będzie to problemem, jeśli nie będziesz musiał później wycofywać się do innego zatwierdzenia lub nawet „wybierania wiśni” później (w tym przypadku bierzesz określone zatwierdzenia i wciągasz je do innej gałęzi, aby użyć). Ale w przeciwnym razie może to stanowić problem.

Prawdopodobnie można to porównać do „migawek” oprogramowania dysku twardego, takich jak Windows (przywracanie). Jeśli zajdzie migawka z wirusem, zabijesz wirusa, ale później musisz wycofać, możesz wrócić do punktu, w którym wirus jest ponownie obecny.

Takie podejście jest również prawdopodobne, aby być problemem podczas korzystania z systemu kontroli wersji i pracy z innych deweloperów, jak to muszą zobaczyć swoją listę rzeczy do zrobienia, które nie ma zastosowania do nich. W rzeczywistości jest to po prostu bałagan, który muszą zignorować i obejść. W naszych zespołach zawsze usuwamy wszystkie komentarze, takie jak stary kod lub „notatki”. Chyba, że ​​są one użyteczne - jest to jednak bardzo rzadkie, ponieważ mamy dokumentację „jak to działa” oraz oprogramowanie do śledzenia tego, co należy zrobić (aka todo).

Ponadto, pracując nad większym projektem, często współpracujesz, często zatwierdzasz i wypychasz, więc możliwe jest, że ich gałąź, nad którą pracują, ma twoją listę rzeczy do zrobienia, jeśli połączyła twoją gałąź z własną. Zatem twoja lista rzeczy do zrobienia jest sprawą wszystkich: D

Podsumowując, jeśli nie pracujesz sam, a zwłaszcza podczas korzystania z kontroli wersji, zaśmieca historię i może być zagraceniem dla innych deweloperów.

I, pod pewnymi względami, jest to sprawa osobista, ale użycie bazy kodów jako „listy rzeczy do zrobienia” nie jest tak naprawdę idealne. Pewnego dnia możesz zostawić coś przypadkiem lub zapomnieć o komentarzu lub przez pomyłkę anulować komentarz.

Podobnie jak w przypadku wielu podejść do architektury, kodowania i sposobu pracy osobiście lub zespołu, każdy scenariusz może wymagać czegoś innego. Więc rozważyć wady wymienione, a korzyści wynikające z zastosowania kontroli wersji, i zdecydować, czy to działa dla Ciebie .

Wygląda na to, że twój recenzent jest trochę dogmatyczny. Nie jestem pewien, czy ktoś przeklina kogoś za skomentowanie kodu to komputer ;-), a nawet pomocny ;-)

Ale poważniej, myślę, że twój recenzent ma rację, że powinieneś poważnie rozważyć użycie git (lub innego systemu kontroli źródła, ale git to rozsądny wybór).

A to może złagodzić niektóre twoje potrzeby skomentowania kodu.

Ale posiadanie listy TODO w kodzie (czy to listy wypunktowane, czy stary kod) - moim zdaniem jest całkiem rozsądne. Możesz jednak zastanowić się, jak to zrobić. Po pierwsze - proponuję myśleć o kimś innym, kto czyta twój kod. Że kimś innym może być Ty, rok po tym, jak rzucisz się i dołączysz do projektu. Lub może to być ktoś zupełnie inny. PO PROSTU napotkanie skomentowanego kodu jest nieco mylące. Może coś takiego:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Osobiście skłaniam się bardziej do czegoś takiego:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

i mogę wrzucić „fragmenty kodu” ze starego kodu jako pomocne.

Korzystanie z git jest trudne (niestety). Zajmie ci to trochę czasu i możesz poczuć, że nie jest to część tego, co próbujesz osiągnąć. Ale jeśli zamierzasz programować użytecznie, musisz nauczyć się tego robić jako część zespołu i komunikować się z zespołem, a git jest właśnie tym, jak się to obecnie robi. A kiedy już go użyjesz, znajdziesz BARDZO pomocne narzędzie / kulę, ułatwiające tworzenie oprogramowania.

Powodzenia!

Istnieje wiele powodów, aby skomentować kod:

• To jeszcze nie jest w porządku, a gdy będziesz gotowy, cofniesz komentarz.
• Tymczasowo komentujesz to, aby zmienić zachowanie podczas debugowania.
• Nie masz pewności, czy kod jest potrzebny, ale nie chcesz go usuwać, dopóki nie przetestujesz więcej.
• Kod jest potrzebny w niektórych wersjach oprogramowania, ale nie w tym.
• Kod jest przestarzały, ale pisanie go zajęło wieki i jesteś do niego emocjonalnie przywiązany. Poza tym może się przydać pewnego dnia.

Problem pojawia się, gdy położysz kod do łóżka, a następnie wrócisz do niego kilka lat później, aby dokonać pewnych czynności konserwacyjnych. Baza kodów jest zaśmiecona skomentowanym kodem. Nie będzie już jasne, dlaczego coś takiego jest, a teraz jest po prostu zagracone.

Jeśli używasz narzędzia do kontroli wersji w połowie przyzwoitego, możesz śmiało usunąć dowolny niepotrzebny kod, bezpiecznie wiedząc, że system kontroli wersji wciąż go przechowuje. Różnica między wersjami ujawni to, co zostało usunięte. Po zaimplementowaniu kontroli wersji, jedyne, co trzeba skomentować, to tymczasowe rzeczy. Jeśli kiedykolwiek znajdziesz skomentowany kod w plikach, nad którymi tak naprawdę nie pracujesz, możesz go po prostu usunąć.

Nie zamierzam powtarzać, dlaczego powinieneś używać kontroli źródła nawet w przypadku projektów jednoosobowych, ponieważ istnieje wiele innych zasobów, które podpowiedzą ci o tym. Ale jedną z głównych powiązanych wad obecnego podejścia jest to, że jeśli skomentujesz kod, ukryjesz go przed IDE (jeśli nie używasz IDE, prawdopodobnie powinieneś go rozważyć).

Na przykład, jeśli chcesz zmienić nazwę metody lub klasy, lub zmienić liczbę parametrów, które przyjmuje metoda, twoje IDE powinno mieć opcję refaktora, aby to zrobić, która znajdzie wszystkie odpowiednie referencje i odpowiednio je zaktualizuje - ale prawdopodobnie wygrał ' t w komentarzach.

Zamiast zgadywać, gdzie należy wprowadzić zmiany, po prostu je wprowadź i pozwól swojemu IDE powiedzieć, gdzie zmiany spowodowały awarię. Następnie możesz skomentować kod bardziej chirurgicznie i, miejmy nadzieję, na krótszy okres czasu, zanim naprawisz cokolwiek zepsute.

Jest źle i powinieneś przestać .

Powód sprowadza się do próby przeprowadzenia dużej ilości refaktoryzacji za jednym razem.

Jeśli komentujesz duże sekcje kodu, popraw trochę i zaloguj się, oznacza to, że wpisałeś niefunkcyjny kod. a cała masa skomentowanych rzeczy, które inni zakładają, jest stara i można ją zignorować

Jeśli nie zameldujesz się często, gromadzisz konflikty scalania i nie rejestrujesz postępów krok po kroku.

Musisz zmienić swoją praktykę pracy, aby w razie potrzeby zatrzymać się w połowie, wszystko nadal działa.

Podejmij kroki dziecka i zamelduj się po każdym

• wyodrębnij interfejs
• napisz test
• refaktoryzuj funkcję

Nie zaznaczaj dużych fragmentów kodu jako „twoich”, komentując je i zabierając do samodzielnej pracy, dopóki nie będą kompletne lub nie powiedzie się.

Jeśli chcesz śledzić, co należy zrobić, użyj tablicy zadań, takiej jak Scrum lub Trello