Dzisiaj będzie pierwszy wpis na blogu nie dotyczący Gita. Szkic tego posta przygotowałem jeszcze jak blog miał być ogólnie o programowaniu, a nie tylko o gicie. Jednak postanawiam go tutaj opublikować, ponieważ nie dotyczy on jakiegoś konkretnego języka programowania. Wpis jest o problemie zostawiania w kodzie komentarzy typu TODO, a to może dotyczyć już sporej liczby programistów.

Wpis dotyczący jakiejś konkretnej kwestii danego języka mógłby się nie spodobać czytelnikom mojego bloga, którzy programują w innym języku programowania. Jednak uważam, że taki ogólny wpis, dotyczący programowania od czasu do czasu mogę opublikować.

O czym w końcu będzie ten wpis? Będzie o zostawianiu komentarzy typu TODO w kodzie. Dlaczego to jest złe i jak na to sobie zaradzić.

167 komentarzy typu TODO w kodzie

Jakiś czas temu w piątkowe popołudnie skończyłem w pracy robić kolejnego taska. Do końca dnia pracy zostało ok. 2 godzin. Widziałem, że w Azure DevOps (dawne Visual Studio Team Services) nie mam już przypisanego żadnego zadania, które zdążę zrobić w całości tego dnia. Postanowiłem przejrzeć komentarze TODO w kodzie i coś poprawić. Pamiętam, że trochę takich komentarzy zostawiliśmy w trakcie pisania aplikacji z nadzieją, że się je poprawi w przyszłości. Taaa… akurat 😛

Korzystam z Resharpera, więc uruchomiłem okno To-do Explorer i zobaczyłem to:

W sumie 167 (słownie: sto sześćdziesiąt siedem) komentarzy typu TODO!!! Nawet jakby każdemu poświęcić tylko 20 minut, to potrzeba ok. 55 godzin, aby wszystko poprawić. Trochę tego się nazbierało.

Wady komentarzy typu TODO

Zacząłem je przeglądać. Czytając komentarze okazało się, że:

• Bardzo niewielka liczba tego typu komentarzy dotyczy mało znaczących rzeczy (w porównaniu z następnymi przykładami 🙂 ) np. zmiana nazwy klasy, drobny refaktoring itp.
• Niektóre dotyczą rzeczy, których nie robiłem, więc czytając jednolinijkowy komentarz w ogóle nie wiedziałem o co w tym chodzi.
• Trochę komentarzy jest napisanych przeze mnie, ale czytając je teraz nie pamiętam dokładnie co miałem na myśli. Jedno zdanie do opisania jakieś buga to zdecydowanie za mało.
• Jest kilka komentarzy po przeczytaniu, których rozumiem o co chodzi, ale nie widzę czemu ta poprawka miałaby służyć. Nie znam kontekstu.
• Jeśli już w miarę wiedziałem o co chodzi, to po krótkiej analizie problemu okazuje się, że to nie jest robótka na 2 godziny, tylko na 4 lub więcej. Podczas analizy wychodzi, że jeszcze to i to przydałoby się od razu poprawić.

Teraz już wiem, że pisanie takich komentarzy to ZŁO. Teraz już tak nie robię.

W pewnym momencie zacząłem również dodawać komentarzy w takim stylu:

// TODO: Kamil (Tomasz Prasołek:2017-12-28 11:03) Może powyższy kod wrzucić do oddzielnej klasy i zwracać tylko stworzone Itemy? Wydaje mi się, że będzie bardziej przejrzyście.

Na początku jest napisane do kogo jest skierowana ta uwaga. W nawiasie autor komentarza wraz z datą i godziną powstania. Następnie główna treść komentarza. Mam do tego zrobiony snippet w Resharperze. Zamiarem pisania komentarzy TODO w taki sposób, było to, aby był skierowany od razu do osoby, która ma się tym zająć. Po drugie widać kiedy ten komentarz został napisany.

Taka jest teoria, ale…

To jest przecież tylko tekst napisany w kodzie. Nie ma żadnego powiązania z programistą. Jeśli nie powiem Kamilowi, że takie coś napisałem to on może tego nawet nie zauważyć.

Komentarz + zadanie

Rozwiązaniem jest jednoczesne napisanie komentarza oraz zadania w systemie zarządzania projektami. W tym zadaniu opiszemy dokładnie jaki jest problem, co trzeba zmienić itd.

W komentarzu dajemy numer zadania i mamy powiązanie. Przy takim podejściu komentarz będzie takim znacznikiem w kodzie gdzie zacząć poprawki. Dodatkowo dzięki Resharperowi możemy zrobić link do naszego systemu zarządzania zadaniami. Opcja ta jest dostępna od wersji 2017.3.

Nasz komentarz będzie np. wyglądał tak:

Podkreślony tekst to jest link do naszego zadania. Można przejść do zadania przy użyciu ALT+ENTER, jeśli kursor jest ustawiony w tej linii. Można też na ten link kliknąć z przytrzymanym CTRL.

Jak to skonfigurować? W opcjach z panelu To-do Explorer musimy dodać nowy wzór:

• Name – nazwa naszego wzoru
• Pattern – wyrażenie regularne, w moim przypadku wygląda tak:
  (?<=\W|^)(?<TAG>TODO_VSTS \#(?<WORKITEM_ID>\d+))(\W|$)(.*)
• Url – link do naszego systemu zarządzania zadaniami:

https://organization.visualstudio.com/DefaultCollection/projectName/_workitems/edit/${WORKITEM_ID}

Działa to tak, że tekst {WORKITEM_ID} z urla zostanie podmieniony na numer zadania wpisany w tym naszym komentarzu TODO_VSTS.

Nie znam się na wyrażeniach regularnych za dobrze. Powyższe napisałem pomagając sobie stroną: https://regex101.com/.

Podsumowanie

Taki sposób pisania komentarzy typu TODO pomoże uporządkować rzeczy, które pozostały do zrobienia. Dzięki temu te rzeczy będą teraz wpisane w system zarządzania zadaniami, a nie będą już te rzeczy ukryte gdzieś w kodzie pod postacią jedno-linijkowego komentarza.

Oczywiście, żeby wszystko co napisałem zadziałało, trzeba dobrze opisać w zadaniu co jest do zrobienia. Jeśli w zadaniu również napiszemy jedno zdanie, to nic taka zmiana pisania komentarzy TODO nie pomoże.

Idealnym rozwiązaniem było by w ogóle nie zostawiać takich komentarzy w kodzie, ale świat przecież nie jest idealny. Czasami po prostu nie mamy czasu, aby coś poprawić teraz, bo są inne ważniejsze rzeczy do zrobienia.