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

21

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.

gaazkam
źródło
Czy przekazujesz komentowany kod kontroli wersji?
Przestań krzywdzić Monikę
1
@ Gooyo w ogóle nie używałem kontroli wersji. Powiedziano mi, że zdecydowanie powinienem zacząć korzystać z kontroli wersji (chociaż jest to osobisty projekt jednoosobowy) i że między innymi kontrola wersji pozwoli mi przestać komentować kod (co powinienem).
gaazkam
4
Jeśli skomentowany kod nie jest widoczny w gałęzi master po ponownym scaleniu (i możesz to zrobić), komu zostanie to zranione ?. Jeśli czujesz potrzebę zatwierdzenia przed pozbyciem się skomentowanego kodu, który sugeruje, że możesz podejmować zbyt duże kroki, ale to inna sprawa.
Przestań krzywdzić Monikę
4
Prawdą jest, że jeśli cmomentujesz kod, możesz go łatwo cofnąć, usuwając komentarz, jednak jeśli zmienisz niektóre rzeczy w niektórych plikach i musisz wrócić, jesteś kompletnie zakręcony bez kontroli wersji. Więc „zacznij korzystać z kontroli źródła” powinno być znacznie powyżej twojego priorytetu niż „nie komentowanie kodu” :)
Walfrat
2
Zaraz, napisałeś, że masz bazę kodu, która jest na tyle duża, że ​​jej fragmenty czasami „muszą być dostosowane do poważnych zmian architektonicznych” - a CHWILOWO NIE KORZYSTASZ Z KONTROLI WERSJI? WTF - poważnie? Żartujesz, prawda? Jeśli jest to naprawdę prawda, masz większe problemy niż pytanie, czy Twój sposób pracy z kodem z komentowania jest w porządku, czy nie.
Doc Brown

Odpowiedzi:

29

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.

JimmyJames
źródło
Nie pamiętam, gdzie go usłyszałem, ale istnieje argument, że ogólnie skomentowany kod nie jest nieszkodliwy, ponieważ nigdy nie jest refaktoryzowany. Zauważ, że zakłada to, że ostatecznie anulujesz komentarz i ponownie użyjesz tego bloku kodu.
Peter M
@PeterM Chodzi o to, że jest w porządku, dopóki się go pozbysz. Nie należy pozostawiać skomentowanego kodu w bazie kodu. Coś, co często robię podczas refaktoryzacji, to komentowanie zmiennych, aby zobaczyć, ile błędów to powoduje, aby pomóc mi zrozumieć, ile to będzie pracy. W zależności od tego, co zamierzam zrobić, mogę to tak zostawić, dopóki nie rozwiążę wszystkich tych problemów, a następnie sfinalizuję zmianę, usuwając skomentowany kod.
JimmyJames
Mam kilka baz kodu, nad którymi pracuję, które są wypełnione komentarzami do zrobienia TODO . Szczerze mówiąc, nie jest tak źle, ponieważ zwykle ma 1-2 wiersze. To, co jak o TODO komentarze jest to, że moja IDE ma „TODO” kartę pobliżu terminalu że auto-zapełnia z tej listy uwag, z podglądem z komentarzem i numer pliku / linii. Chodzi o to, że przydaje się, gdy w konkretnej firmie nie wstrzymują się z problemami, mimo że używają Git / Github. Tak, a co możesz zrobić, spróbuj przekonać kierownictwo do korzystania z Git Problemów zamiast Arkuszy Google? Tak, próbowałem i nie udało się. No cóż. TODO komentuje, że tak!
Chris Cirefice
6

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 .

James
źródło
Dlatego pracujesz nad gałęziami operacji i używasz zgniatanych połączeń. Kod pracujący nigdy nie powinien być widziany przez innego programistę, dlatego nie powinno mieć znaczenia, jaką metodę wykorzystano do jego opracowania.
Jules
4

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!

Lewis Pringle
źródło
2

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ąć.

Simon B.
źródło
1
To są właśnie powody, dla których powinieneś raczej używać SCM (i dźwigni w nim)
Timothy Truckle
2

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.

Chris Cooper
źródło
1

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

Ewan
źródło