Czy komentarze TODO mają sens? [Zamknięte]

86

Pracuję nad dość dużym projektem i dostałem zadanie wykonania kilku tłumaczeń. Było mnóstwo etykiet, które nie zostały przetłumaczone i podczas gdy przeglądałem kod, znalazłem ten mały fragment kodu

//TODO translations

To sprawiło, że pomyślałem o znaczeniu tych komentarzy dla siebie (i innych?), Ponieważ miałem wrażenie, że większość programistów po tym, jak zrobili pewien fragment kodu i robi to, co powinno, nigdy na to nie patrzą, dopóki nie aby go utrzymać lub dodać nową funkcjonalność. Aby to TODOna długo zaginęło.

Czy ma sens pisanie tych komentarzy, czy powinny być napisane na tablicy / papierze / czymś innym, gdzie pozostają w centrum uwagi programistów?

Ivan Crojach Karačić
źródło
2
(niektóre) IDE je śledzą. Używam ich swobodnie, gdy nie do końca opracowałem implementację modułu, ale umowa jest dla mnie (lub innych) wystarczająca, aby kontynuować rozwój innego pokrewnego elementu.
smp7d,
3
TODO jest dla mnie bardziej jak „powinien zrobić, aby zoptymalizować, ale nie trzeba go wysyłać”
Jake Berger,
8
Ilekroć przychodzi mi do głowy zadanie do wykonania lub przypadek, który należy sprawdzić pod kątem bieżącej funkcji, nad którą pracuję, przerywam to, co piszę (nawet w połowie zdania) i dodam do tego TODO (nawet jeśli to tylko linia powyżej) . Pomaga to uniknąć tych błędów „O tak, nawet o tym myślałem” . Zanim zatwierdzę tę funkcję, sprawdzam TODO. Nigdy się nie angażują, ale odkąd zacząłem to robić, moja liczba błędów drastycznie spadła .
BlueRaja - Danny Pflughoeft,
8
Zawsze używam, #warning TODO: …jeśli nie chcę zapomnieć o TODO.
prawej
2
@WTP: Visual Studio, R #, Netbeans, Eclipse itp. Itd. Wszystkie zawierają narzędzia do przeglądania wszystkich TODO w obrębie rozwiązania / obszaru roboczego. Ten stary hack nie jest już potrzebny.
BlueRaja - Danny Pflughoeft,

Odpowiedzi:

107

Zwykle używam // todokomentarzy do rzeczy, które muszą się wydarzyć, ale nie mogę tego zrobić natychmiast.

Dbam też o to, żeby ich ścigać - szukam ich (Visual Studio ma fajną funkcję, w której będzie wyświetlał takie komentarze) i upewniam się, że wszystko zostało zrobione.

Ale, jak mówisz, nie wszyscy są wobec nich pilni i jak wiele komentarzy, z czasem gniją.

Powiedziałbym, że jest to bardziej osobiste preferencje - tak długo, jak dokumentujesz, co należy zrobić, i gonisz za tym, nie ma znaczenia, czy to jest // todo, notatki pocztowe czy biała tablica (gdzie mogą również nie skończyć podejmowane działania).

Oded
źródło
18
Eclipse wyróżnia je i konsoliduje ich listę również dla Ciebie. Pisanie komentarza do zrobienia TODO, gdy myśl jest w twoim umyśle, nie jest złym pomysłem, nawet jeśli nigdy nie uda ci się tego zrobić. Jakaś wspaniałomyślna dusza może przeglądać kod w poszukiwaniu rzeczy do zrobienia (OSS).
płyty grzejne
4
Resharper ma również fajną listę TODO, działa lepiej niż domyślny VS (przegląda więcej plików).
CaffGeek,
Tak, biorąc pod uwagę listę w twoim IDE, są one pomocne. Powiedziałbym, że w przeciwnym razie mają bardzo ograniczone zastosowanie, ponieważ baza kodów może być ogromna.
Inżynier
4
Z powodu zgnilizny komentarzy zawsze umawiam się i inicjuję swoje komentarze. Jeśli komentarz ma trzy lata od czterech kontrahentów temu, prawdopodobnie możesz go usunąć.
user1936,
2
Odkąd wymieniono resharper i daty, używam prostego szablonu Live Resharper z „// TODO $ user $ ($ date $) -”
dark fader
56

Nowoczesne IDE rozpoznają TODOkomentarze i jako takie są widoczne we własnym panelu / oknie / zakładce, więc teoretycznie nie są zagubione (myślę, że Eclipse i Visual Studio, oba znam na tyle, aby pamiętać, że je rozpoznają).

Można nawet skonfigurować dodatkowe komentarz słów takich jak FIXME, BEWARElub cokolwiek innego chcesz dostosować. Jednak inni programiści Twojego projektu będą musieli dostosować swoje IDE w ten sam sposób.

Teraz napisałem „teoretycznie”, ponieważ choć nie zagubiony, TODO bardziej niż często odnosi się do czegoś, co nie jest potrzebne, aby aplikacja działała poprawnie „w tej chwili”. I „w tej chwili” może trwać od 5 minut do 5 lat, w zależności od rodzaju / wielkości projektu :-)

Wreszcie, moim zdaniem, nadal sensowniej jest mieć je w kodzie, we właściwym miejscu, dokładnie odpowiadając na pytanie „gdzie mam dokonać zmiany”, niż gdzie indziej poza kodem.

Edycja: Jak napisano w artykule Wikipedii na temat komentarzy , w tym datę i właściciela TODO uważa się za dobrą praktykę.

Jalayn
źródło
32
Myślę, że data i właściciel TODO to po prostu hałas. Do tego służy kontrola wersji (i funkcja winy) (jeśli naprawdę potrzebujesz informacji).
sleske,
3
Nie sądzę, by wikipedia z napisem „Jest zalecane” jest jakikolwiek cytat; czujność zapachu. Lepszy link do artykułu, który to twierdzi.
fresnel,
@ phresnel dobrze jest cytat związany z tą „radą”, więc nie czułem potrzeby powtarzania tego tutaj, w przeciwnym razie zgadzam się z faktem, że cytowanie faktów z Wikipedii nie popartych niczym może być niebezpieczne
Jalayn
@sleske Zgadzam się na utrzymanie minimalnego poziomu hałasu ALE myślę, że IDE nie przekazują ci automatycznie tych informacji z repozytorium (chyba że się mylę, będziesz musiał ręcznie porównać wersje), jeśli nie napiszesz tego wprost .
Jalayn
1
Funkcja adnotacji w programie Visual Studio ułatwia sprawdzenie, kto ostatnio rejestrował zmiany w różnych częściach pliku, nad którym pracujesz, i według którego zestawu zmian. Nie idealny, ale w wielu przypadkach (szczególnie z TODOkomentarzami) wystarczająco blisko, aby był użyteczny.
CVn
13

To może mieć jakiś sens, przynajmniej czasami ich używam. Kluczową kwestią jest stosowanie spójnych znaczników, takich jak TODOlub FIXMEtak, aby można je było łatwo znaleźć za pomocą prostego wyszukiwania tekstu.

Na przykład „szybkie i brudne” rozwiązania są wygodne do etykietowania, na przykład:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Jeśli kod robi to, co powinien, i nikt nie narzeka, komentarz nie zaszkodzi. Jeśli kiedykolwiek będzie czas na upiększenie kodu, łatwo jest zacząć od wyszukiwania FIXMEetykiet.

Joonas Pulakka
źródło
3
„FIXME” i „TODO” mają dla mnie różne znaczenie. Tłumaczenie, wartość zakodowana na stałe lub wyłapanie wyjątku ex.printStacktrace()to dla mnie TODO. Z drugiej strony FIXME poradziłoby sobie z wyjątkami, które czasami występują, wyciekiem pamięci lub innym rodzajem błędu, który udało się zlokalizować, ale nie do końca przeanalizowano / naprawiono.
rds
10

W mojej branży programiści są zachęcani do wprowadzania wpisów JIRA (itp.) Zamiast dodawania komentarzy do todo, ponieważ nie wszyscy mają szansę je zobaczyć // todo. Ale czasami w dużych projektach niestandardowy atrybut jest definiowany w następujący sposób:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

Następnie można w ten sposób udekorować metodę ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

Wyżsi mogą przyjść i zebrać je automatycznie. Proste // todoprzypomnienie może być przesadzone , ale jest skuteczne. Wymaga to także platformy .NET.

Garry
źródło
5
Komentarz TODO jest zsynchronizowany z wierszem kodu. Według mnie bilet ma bardziej globalny i wyższy poziom. I myślę, że ta adnotacja to przesada. TODO ma większą szansę na pracę nad większą liczbą redaktorów.
rds
6
Twoja branża? Które to? Nie znam całej branży, która zachęca do korzystania z JIRA ?!
fresnel
7

TODO to tylko podformularz komentarza. Komentarze są bardzo przydatne, jeśli pisarz jest w ogóle wykwalifikowany w wiedzy, co przekazać i jak to przekazać. Poczucie humoru można również zastosować tutaj w małych dawkach, aby zachwycić opiekunów po latach.

W zeszłym roku dostałem telefon, że część mojego kodu została wycofana. Byłem pod wrażeniem, że był w produkcji i przetrwał konserwację przez 16 lat. Pamiętaj więc, że Twój kod może trwać DŁUGO. Komentarze na temat zamiarów, przyszłych potrzeb itd. Mogą znacznie pomóc komuś, kto za kilka lat patrzy na kod po raz pierwszy.

Pete Mancini
źródło
1
Jeśli był tam od ponad dekady, nie był tak naprawdę potrzebny, dlatego dodanie TODOkomentarza nie miało sensu.
CVn
2
To zakłada, że ​​nigdy się nie zmienią. Podobnie jak kod, komentarze mogą ulec zmianie wraz z dodawaniem, usuwaniem i modyfikacjami. Listy TODO są bardziej prawdopodobne, że zostaną zmienione w ten sposób. Jestem pewien, że w ostatnim dziesięcioleciu od ostatniego dotknięcia kodu komentarze zostały zmienione.
Pete Mancini,
6

Z mojego doświadczenia wynika, że ​​to zależy. Głównym czynnikiem jest to, czy zespół jest wystarczająco zdyscyplinowany, aby zastosować się do tych „małych” komentarzy. Jeśli tak, to mają sens. Jeśli tego nie zrobią, te komentarze to tylko strata czasu i warto przyjrzeć się innym opcjom, np. Kartom historii.

Osobiście używam komentarzy TODO od czasu do czasu, ale zazwyczaj są one krótkotrwałe i zwykle mam ich bardzo małą liczbę, jak jeden, dwa lub trzy. Używam ich bardziej jako markera w bazie kodu niż cokolwiek innego. Jeśli zbyt długo czekam, aby się nimi zająć, to zapominam o tym, co moim zdaniem musiałem „zrobić”.

Zawsze wolałbym nie używać ich, a zamiast tego używać odpowiednich kart opowieści, zaległości lub tym podobnych. Użyj jednego mechanizmu do jednego zadania.

Manfred
źródło
6

Kiedyś pisałem je w przeszłości, ale okazało się, że zwykle ich nie śledzisz.

Dlatego teraz używam ich tylko do oznaczania rzeczy, nad którymi chcę pracować, zaraz po skończeniu tego, czym jestem zajęty. Na przykład implementuję nową funkcję i zauważam, że funkcja, której używam, ma mały błąd; Robię FIXME, aby to naprawić, aby uniknąć wykolejenia w moim bieżącym zadaniu.

Aby mi pomóc, nasze kompilacje CI są skonfigurowane tak, aby kończyły się niepowodzeniem, jeśli w kodzie są FIXME :-).

Jeśli zauważysz potencjalne problemy, których nie można od razu rozwiązać, otwórz dla nich bilet / błąd / problem. W ten sposób można nadać im priorytet jak wszystkie błędy. Wydaje mi się, że jest to o wiele lepsze niż problemy z DB i błąd w TODO.

Opcjonalnie możesz następnie wprowadzić TODO z identyfikatorem błędu :-).

Śleske
źródło
3

Myślę, że TODOkomentarze do pewnego stopnia mają sens. Szczególnie jeśli pracuje iteracyjnie (co jest powszechne w sklepach zwinny i TDD), nie będzie rzeczy, które można rozpoznać się będzie potrzebne przed długi, ale czego nie chcą zrobić objazd do wdrożenia w prawo, potem i tam.

Brzydkie jest to, że takie komentarze pozostają w bazie kodu. Gdy aktywnie pracujesz nad funkcją, możesz ją zostawić, ale gdy tylko zbliżysz się do jej ukończenia, powinieneś skupić się na ich usunięciu. Jeśli nie chcesz przejść przez pracę polegającą na zastąpieniu ich odpowiednim, działającym kodem, przynajmniej weź pod uwagę odpowiednią funkcjonalność. Aby pożyczyć przykład @ JoonasPulakka, w którym kod początkowo mówi

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

możesz to zmienić na coś takiego

ConnManager.getConnection(GetDatabaseName());

na razie GetDatabaseName () jest kodem pośredniczącym, który po prostu zwraca ten sam ciąg, od którego zacząłeś. W ten sposób istnieje wyraźny punkt przyszłej rozbudowy i wiesz, że wszelkie wprowadzone tam zmiany zostaną odzwierciedlone wszędzie tam, gdzie potrzebna jest nazwa bazy danych. Jeśli nazwa bazy danych jest nawet umiarkowanie ogólna, może to być znaczna poprawa w zakresie konserwacji.

Osobiście używam własnego słowa kluczowego zamiast ściśle TODO, chociaż cel jest taki sam: zaznaczanie rzeczy, które wiem, że będą wymagać powtórzenia. Ponadto przed wpisaniem kodu przeprowadzam globalne wyszukiwanie kodu źródłowego dla tego słowa kluczowego, które jest tak wybrane, aby normalnie nie pojawiało się nigdzie w kodzie. Jeśli zostanie znaleziony, wiem, że coś zapomniałem i mogę to naprawić.

Jeśli chodzi o dołączenie nazwy / podpisu programisty do komentarza, myślę, że to przesada, jeśli masz system kontroli wersji kodu źródłowego ( tak , prawda?). W takim przypadku jego funkcja obwiniania powie Ci, kto dodał komentarz, a dokładniej, kto ostatnio zarejestrował zmianę, która dotknęła komentarza. Na przykład w Visual Studio można to łatwo osiągnąć za pomocą funkcji „Adnotacja”, która znajduje się wśród funkcji kontroli źródła.

CVn
źródło
3

Jeśli napiszesz TODO lub FIXME z myślą, że ktoś inny to naprawi, gdy dojdą do tego kodu w nieokreślonej przyszłości, powiedziałbym, że nie przejmuj się. Zaśmiecą kod i zagracą część raportowania twojego IDE, która zbiera te informacje.

Aby były użyteczne, powinny zapewniać możliwość dodania kodu do zakładek w (bardzo) bliskiej przyszłości, abyś mógł szybciej wrócić do właściwego stanu umysłu. Innymi słowy, umieszczasz je w kodzie tylko po to, aby usunąć je JAK NAJSZYBCIEJ.

Wszystko, co już przeżyło, powinno zostać umieszczone w bazie błędów, tam gdzie należy.

W naszym życiu jest wystarczająco dużo hałasu, nie twórzmy nowych fanfarów, które krzyczą o uwagę, gdy są potrzebne gdzie indziej.

Moje 2 centy

Newtopian
źródło
2

Zwykle nie robię komentarzy // TODO, ale przechowuję je w osobnym pliku. Nadal nie mogę znaleźć / napisać oprogramowania online, aby łatwo nimi zarządzać, więc pliki TODO są nadal dla mnie najbardziej przydatne, ponieważ kiedy otwieram projekt po nawet krótkim czasie, zapominam, co robić teraz, a potem zajmuję się plikiem TODO i wykonuję zadanie . Mam „filename.cpp 354: Przekoduj to bla bla bla” i jest to o wiele bardziej przydatne niż wyszukiwanie // komentarza TODO w pliku. Zrobiłem // TODO Earlera, kiedy byłem leniwy, ale po prostu usuwam te stare // TODO-y z pliku źródłowego i nie naprawiam ich, gdy projekt działa dobrze. Zdecydowanie zalecam przeniesienie wszystkich // TODO z sosu do osobnego miejsca i trzymanie ich razem z innymi todo, aby ułatwić priorytety zadań. Priorytet jest naprawdę trudny do zrobienia TODO, kiedy masz wszystkie swoje TODO w różnych plikach i różnych projektach.

cnd
źródło
7
A następnie wstawisz nową funkcję do pliku.cpp, powiedzmy w wierszu 200 w przypadku twojego przykładu, ponieważ pomocna jest zmiana fragmentu kodu. Nagle twoje odniesienie jest bez znaczenia. Wolę IDE wskazujące mi je tam, gdzie są teraz , a nie tam, gdzie były, kiedy zobaczyłem taką potrzebę TODO.
CVn
Tak, masz rację) czasami trudno mi znaleźć linię, ale ja sobie z tym radzę. I tak. Mogę użyć obu, aby łatwo znaleźć w pliku lub IDE, ale wiedzieć, co robić w osobnym miejscu.
cnd
2

Myślę, że tam świetnie, ale nie sam. Na przykład:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

To podejście działa całkiem nieźle. Chociaż muszę powiedzieć, że nawyk rzucania wyjątków w celu przypominania o uzupełnieniu kodu nie jest tak naprawdę najbardziej profesjonalnym podejściem. Ale uratowało mnie to w niektórych przypadkach, w których myślisz, że coś ukończyłeś, a nawet zapisałeś, że ukończyłeś, gdy tego nie zrobiłeś.

Edward
źródło
2
W takim przypadku możesz po prostu rzucić, new NotImplementedException()co implikuje ToDo.
CodesInChaos,
W CI lubię korzystać assert(0 && "TODO[cmaster]: Add click event logic");. Prosty i bardzo skuteczny w przekazywaniu mi wiadomości, jeśli zapomnę TODO ...
cmaster
1

Ogromną zaletą todo komentarzy w porównaniu z jakimkolwiek innym milionem sposobów tworzenia listy zadań jest to, że komentarze todo podróżują z kodem, więc nie można ich rozdzielić.

Prawdopodobnie bardziej odpowiednim miejscem na takie rzeczy jest śledzenie problemów, a nie kod.

Wyatt Barnett
źródło
0

Zdecydowanie zalecam wpisanie każdego TODO lub FIXME do formalnego dziennika. Jeśli tak nie jest, można je łatwo przeszukiwać i powinna to być faza w każdej iteracji, aby sprawdzić, czy nie ma wybitnych TODO i FIXME. Można je następnie skatalogować i albo ustawić na natychmiastowe rozwiązanie, albo zespół może zaplanować ich naprawę w odpowiednim czasie.

Wreszcie po naprawieniu należy je usunąć - jeśli nie zostaną wyeliminowane w systematyczny sposób po rozwiązaniu, stracą swoją skuteczność.

Konkluzja: są lepsze niż w ogóle nie rejestrowanie problemów, ale w rzeczywistości musisz je utrzymać.

Marcin
źródło
-1

IntelliJ faktycznie ostrzeże Cię, jeśli spróbujesz zatwierdzić kod, który ma nowe TODO. Tak więc zawsze możesz interpretować TODO jako „tak naprawdę powinno się to zdarzyć do czasu, gdy dokonam”.

ripper234
źródło
-1

Kiedy uważasz „TODO” za semantyczną etykietę twojego komentarza, myślę, że ma to sens.

W standardach kodowania mojej firmy określamy, że inicjały odpowiedzialnego programisty muszą być dołączone do TODO ( tzn. Wpisałbym „SAA TODO:”). Myślę, że jest to przydatne, przynajmniej jako konwencja, ponieważ w przeciwnym razie istnieje pokusa, aby pozostawić kod niestandardowy z notatką TODO dla niektórych przyszłych programistów.

Pomocne jest skonfigurowanie wielu IDE w celu dodawania tych komentarzy do listy zadań, co pozwala traktować je podobnie do budowania zapisów i nie zapominać w nieskończoność.

Stewart
źródło
-2

Bardziej nieznośną, ale skuteczną metodą jest prawdopodobnie przekształcenie komentarzy do zrobienia w komunikaty kompilatora, w ten sposób ty i wszyscy inni widzicie je podczas kompilacji programu.

w Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}
Peter Turner
źródło
-4

Z mojego doświadczenia TODOwynika, że ​​powinienem być używany do wskazania, że ​​fragment kodu nie jest użyteczny i mówi czytelnikowi, co jest potrzebne, aby był użyteczny (lokalnie lub gdzie indziej).

TODOadnotacje nie powinny być używane do wskazania, że ​​jakiś fragment kodu byłby ładniejszy, gdyby został w jakiś sposób zmodyfikowany. Przykłady obejmują brudny kod, który byłby łatwiejszy w utrzymaniu, gdyby został przepisany lub dodatkową funkcję, której nikt jeszcze nie potrzebuje. Te adnotacje zwykle gromadzą się i grep TODOprzynoszą bezużyteczne wyniki.

Martin Jambon
źródło
czy to tylko Twoja opinia, czy możesz jakoś to zrobić?
komara
To moja opinia i porady oparte na moim doświadczeniu. Niektóre osoby używają komentarzy TODO do powiedzenia „Wiem, jak napisać dobry kod, ale nie zamierzam tego robić, bo mnie to nie obchodzi, ale hej, napisałem TODO tutaj, więc naprawdę pokazuje, że wiem, jak napisać czysty kod”.
Martin Jambon,