Dodajesz komentarze w swoim kodzie? Prawdopodobnie zwiększasz przez to jego skomplikowanie, a także obniżasz czytelność. W tym wpisie dowiesz się kiedy naprawdę warto dodać komentarz, a kiedy jest on jedynie problemem i powoduje więcej konsekwencji.

Czym są komentarze?

Na sam początek powiedzmy sobie czym tak naprawdę komentarze są. Zdaję sobie sprawę, że jest to wiedza na poziomie gimnazjum, jednak przytoczmy definicję tego mechanizmu. Komentarz jest więc fragmentem kodu, który nie jest brany pod uwagę przez kompilator, interpreter czy transpilator. On po prostu jest, a w momencie uruchomienia procesu budującego nasz program lub skrypt, komentarz zostaje pominięty. Służą one do tego, abyśmy nie pogubili się we własnym kodzie i w razie czego mogli pozostawić informację, że coś jest nie tak, wymaga doprecyzowania lub zwyczajnie wyjaśnić, co dany fragment robi.

Dlaczego komentarze to zazwyczaj zły pomysł?

Zazwyczaj, stosowanie komentarzy jedynie zaciemnia kod i powoduje, że jest on niepotrzebnie dłuższy oraz mniej czytelny. Osobiście jestem z obozu hejtującego stosowanie tego mechanizmu, ponieważ uważam, że dobrze napisany kod nie wymaga żadnego komentarza. Skąd takie podejście? Spójrzmy na poniższy przykład. Mamy tutaj funkcję, która nazywa się calculate i zgodnie z tym, co jest napisane w komentarzu, wylicza przychód dla roku podanego w jej argumencie. Jak myślisz, co w poniższym kodzie jest nie tak? Zgadza się, komentarze!

// it calculates yearly income
// as parameter you need to pass year
function calculate(y: number) {
  // invoices for passed year
  const invoices = invoices.find({ year: y });

  // sum of invoices' totals
  return invoices.reduce((income: number, invoice: Invoice) => invoice.total, 0);
}

Kod bez komentarzy

Sprawdźmy, jak możemy przepisać powyższy przykład tak, aby komentarze przestały być potrzebne. Zmieńmy nazwę funkcji na calculateYearIncome, dzięki czemu będziemy mogli usunąć jedną linijkę z komentarza ponad nią. Następnie, argument nazwijmy year, co pozwoli na usunięcie całego komentarza nad funkcją.

function calculateYearIncome(year: number): number {
  // invoices for passed year
  const invoices = invoices.find({ year });

  // sum of invoices' totals
  return invoices.reduce((income: number, invoice: Invoice) => invoice.total, 0);
}

Komentarz nad stałą jest całkowicie zbyteczny, ponieważ nazwa stałej sama w sumie mówi nam, że będą w niej faktury. Z kolei wywołanie metody find z argumentem year, że będą to faktury dla roku przesłanego w argumencie.

function calculateYearIncome(year: number): number {
  const invoices = invoices.find({ year });

  // sum of invoices' totals
  return invoices.reduce((income: number, invoice: Invoice) => invoice.total, 0);
}

Na usunięcie ostatniego komentarza jest wiele sposobów. Możemy np. pójść w stronę paradygmatu programowania deklaratywnego i utworzyć dodatkową funkcję, przecież jest to dodatkowe zachowanie, które może zostać później ponownie użyte.

function calculateYearIncome(year: number): number {
  const invoices = invoices.find({ year });

  return sumInvoicesTotals(invoices)
}

function sumInvoicesTotals(invoices: Invoices[]): number {
  return invoices.reduce((income: number, invoice: Invoice) => invoice.total, 0);
}

Kiedy warto komentować kod?

Nie jest oczywiście tak, że komentarze są całkowicie bezużyteczne. Czasami naprawdę zachodzi potrzeba dodania komentarza. Przykładowo, może zajść konieczność szybkiego zanotowania, że coś musi zostać w przyszłości zrobione, tzw. „TODO” – osobiście, wolę osobny task, jednak nie neguję takiego postępowania. 

Inną sytuacją z którą możemy się spotkać, to nieoczywisty kod, który powstał nie z naszej winy, a chcemy oszczędzić czas osobie, która go po nas przejmie. Wyobraźmy sobie, że komunikujemy się z zewnętrznym API i (czysto teoretycznie) w dni nieparzyste zwraca ono zwrotki w jednej postaci, a w dni parzyste w innej. Ktoś, kto pierwszy raz spojrzy na taki kod, może się zdziwić. Dobrym wyjściem będzie zostawienie komentarza. 

async function obtainInvoicesFromComar(): Invoice[] {
  const response = await comarHttpClient.getInvoices();

  // Comar API returns invoices under "invoices" property only on odd days.
  return InvoiceMapper.fromComarInvoices(response.invoices ?? response);
}

Podsumowanie

• Spróbuj tworzyć kod w taki sposób, aby komentarz nie był potrzebny.
• Nie stosuj komentarzy dla oczywistych fragmentów, bo będą one jedynie zaśmiecać Twój projekt.
• Jeżeli już musisz napisać komentarz, zrób to jak najkrócej i treściwie.