Skip to content

Komentarze – ZK #1

Niewłaściwe informacje

W komentarzach powinno się przechowywać tylko informacje przeznaczone do zapisania właśnie w nich. Oznacza to, iż nie wolno umieszczać w nich informacji, które powinny być przechowywane w innych systemach!  Historia zmian w kodzie zarezerwowania jest więc dla VCS (systemu kontroli wersji). Do utrwalania informacji dotyczących błędów oprogramowania powinno używać się Bugtracker’ów. Przetrzymywanie linijek zakomentowanego historycznego kodu, który z kolejnymi zmianami zaczyna się nawarstwiać jest co najmniej nieetyczne (i raczej mało skuteczne). Różne metadane, takie jak np. autorzy, data utworzenia lub ostatniej modyfikacji również nie powinny być zapisane w komentarzach. Komentarze powinny dotyczyć tylko i wyłącznie informacji technicznych na temat funkcjonowania samego kodu!

Przestarzałe komentarze

Komentarz przestarzały to innymi słowy komentarz, który ze względu na zmiany w kodzie stał się błędny lub nieistotny. Najlepszą praktyką jest więc tworzenie komentarzy, które raczej nie utracą swojej aktualności. Musimy więc w stosownym momencie rozważyć czy dana informacja powinna być przekazana za pomocą komentarza, czy też poprzez zaprojektowanie odpowiedniej struktury pisanego kodu, który swoim samym wyglądem przystępnie opisuje wykonywaną czynność. Logicznym jest więc, iż gdy natrafimy na komentarze przestarzałe to powinniśmy postarać się je zaktualizować lub usunąć. Komentarz, który od dawna nie był aktualizowany pomimo zmiany funkcjonalności kodu, której dotyczył traci z nią łączność i może wprowadzać innych programistów w błąd.

Nadmiarowe komentarze

Wspomniałem już o tym nieco w poprzednim akapicie. Komentarz jest nadmiarowy, jeżeli opisuje fragment kodu, który jest wystarczająco czytelny i elementarny.

Przykładowo:

// This method adds two ints
public int add(int a, int b) {
  return a + b; // Returns a + b
}

Dotyczy to również pisania np. dokumentacji Javadoc, która posiada w sobie dokładnie takie same informacje jak sygnatura metody:

/**
* @param a
* @param b
* @return
*/
public int add(int a, int b) {
  return a + b; // Returns a + b
}

Innymi słowy – komentarz powinien zawierać informacje, które nie mogą być przekazane za pomocą samego kodu.

Źle napisane komentarze

Jeżeli chcemy napisać komentarz, powinniśmy być pewni, że jest on wart napisania (jakkolwiek by to nie brzmiało). Musimy postarać się napisać go dobrze (czyli biorąc pod uwagę również rzeczy powyżej opisane). Nie bójmy się poświęcić chwili czasu na dobór odpowiedniego słownictwa oraz zastosowanie poprawnej gramatyki i interpunkcji. Starajmy się nie pisać chaotycznie, a także pomijajmy rzeczy oczywiste. Informacje zapisane w komentarzach powinny być przedstawione w sposób lakoniczny!

Zakomentowany kod

Dlaczego zakomentowany kod jest taki zły? Powodów jest kilka. Po pierwsze – skąd programista ma znać wiek takiej dryfującej połaci kodu nie przeglądając dokładnie systemu kontroli wersji? Nie będzie również posiadać informacji na temat istotności takiego kodu. Może przecież zawsze założyć, że ktoś specjalnie umieścił tam taki komentarz i jest komuś do czegoś potrzebny, a w efekcie będzie prawdopodobnie bał się go skasować. Zakomentowany kod, który tkwi w stanie hibernacji na łamach naszego projektu z każdym kolejnymi zmianami traci na swojej aktualności i znaczeniu. Wyobraźcie sobie sytuację, w której czytacie komentarz wykorzystujący zmienne, które dawno zostały przemianowane na inne lub całkowicie usunięte, stawiający na przestarzałe konwencje lub opisujący przestarzałą wersję funkcjonalności. Nie jest to zbyt przyjemna perspektywa prawda? Dodatkowo komentarz taki będzie odwracać uwagę programisty, który zamiast robić coś pożyteczniejszego będzie musiał zrozumieć o co w tym wszystkim chodzi.

Moja rada? USUŃ TO.

 


Informacje na temat cyklu i źródeł:

Facebooktwitterredditlinkedinmail
Published inProgramowanie