Komentarze TODO

Istnieje pełno narzędzi do zarządzania zadaniami, są issues na GitHubie, ale kiedy chcemy zanotować szybko zadanie dotyczące kodu, nad którym akurat pracujemy to możemy użyć komentarza.

Takie komentarze pomogą nam szybko przypomnieć sobie co już mamy zrobione, a co nie. Na przykład

class Server {
   private:
    void doStuff(); //TODO

   public:
    void run();
}

void Server::run() {
    while(true) {
        doStuff();
    }
}

Patrząc na deklarację klasy widzimy, które metody zostały nam do zaimplementowania. Trzeba tylko pamiętać, żeby po zaimplementowaniu usunąć komentarz.

Lub komentarz może opisywać sposób w jaki coś chcemy zrobić, a na ten moment napisaliśmy tylko kawałek implementacji.

void doStuff() {
    int times = 5; //TODO: calculate this value based on other fields of the class
    for(int i = 0; i < times; i++) {
        ...
    }
}

Generalnie chcemy utrzymać jedno zadanie na linię kodu, a kiedy potrzebujemy więcej opisu i koniecznie chcemy zostawić taki komentarz w kodzie to powinniśmy poprzedzić każdą linię //TODO:.

Dlaczego?

Ponieważ wtedy możemy wyszukiwać naszych zadań w plikach przy pomocy różnych narzędzi.

Pierwszym z nich jest dostępny pod Linuxem grep

grep TODO * -rn

Szukamy frazy “TODO” we wszystkich plikach w tym floderze (*), rekurencyjnie -r i chcemy numer linii, w której ta fraza występuje -n.

To samo możemy osiągnąć w PowerShellu, jeśli korzystacie z Windowsa

Get-ChildItem . -r | Select-String -pattern TODO

A jeśli korzystacie z bardzo starego Windowsa i nie macie PowerShella tylko CMD.EXE, to znalazłem w Internecie, że to powinno dać ten sam efekt (nie mam jak przetestować)

findstr /spin /c:"TODO" *

Informacje o tym jak i dlaczego takie polecenie, znajdziecie tutaj.

Po za tym wiele IDE takich jak np. Visual Studio ma wbudowane narzędzia wyświetlające wszystkie komentarze TODO.

Podsumowując, czasem robienie takich krótkich komentarzy TODO w kodzie jest bardzo przydatne, bo ukróca czas między znalezieniem informacji co chcemy zrobić i miejscem w kodzie, gdzie chcemy to zrobić. Ale generalnie nie polecam zostawiania takich komentarzy na dłuższy czas, bo można je zgubić (chyba że korzystamy z metod wyszukiwania ich, opisanych powyżej) i zapomnieć.