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

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?

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

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ę.

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.

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.

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.

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.

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 :-).

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.

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

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.

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ś.

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.

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

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”.

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

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

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.