„I”, „My” lub Ani w dokumentacji kodu

Uważam, że piszę (mam nadzieję) pomocne komentarze w dokumentacji typu C ++:

The reason we are doing this is...

Powodem, dla którego używam słowa „my” zamiast „ja” jest to, że dużo piszę w środowisku akademickim, gdzie „my” jest często preferowane.

Oto pytanie. Czy istnieje dobry powód, aby preferować jeden nad drugim w dokumentacji kodu:

1. Użyj „My”: Powodem tego jest ...
2. Użyj „I”: Powodem, dla którego to robię jest ...
3. Użyj mojego imienia: Powodem [my name]tego jest ...
4. Głos pasywny: Powodem tego jest ...
5. Ani: Zrób to, ponieważ ...

Wybieram numer 1, ponieważ jestem przyzwyczajony do pisania w ten sposób, ale dokumentacja nie jest dla pisarza, ale dla czytelnika, więc zastanawiam się, czy dodanie nazwy programisty jest pomocne, czy to tylko dodaje kolejną rzecz, która musi zostać zmienione podczas utrzymywania kodu.

Poszedłbym z:

# 6. Deklaratywny: ...

Zamiast powiedzieć „Powodem tego było to, że każdy Foo musi mieć pasek”, wystarczy powiedzieć „Każdy Foo musi mieć pasek”. Zamień komentarz w aktywne stwierdzenie przyczyny, a nie pasywne. Ogólnie jest to ogólnie lepszy styl pisania, lepiej pasuje do natury kodu (który coś robi ), a the reason this was donefraza nie dodaje żadnych informacji. Pozwala to również uniknąć dokładnie napotkanego problemu.

Nie wolę żadnego z nich i właściwie zrezygnowałbym z tego wprowadzającego zdania i przechodziłbym do sedna. Staram się również unikać po prostu mówienia „to”, ponieważ nie pozostawia żadnego sposobu, aby stwierdzić, czy komentarz jest zsynchronizowany z kodem. Innymi słowy, zamiast:

// The reason this was done is to prevent null pointer exceptions later on.

Powiedziałbym:

// Frobnicate the widget first so foo can never be null.

Fakt, że dodajesz komentarz, oznacza, że ​​podajesz powód, więc nie musisz niepotrzebnie informować osób, które wyjaśniają powód. Podaj powód tak konkretny, jak to możliwe, aby wiedzieli jak najdokładniej, jak zachować ten kod później.

W języku C # (i w większości narzędzi do dokumentacji w innych językach) istnieje różnica między dokumentacją a komentarzem w wierszu. Osobiście uważam, że zawsze powinieneś używać formalnych komentarzy w stylu deklaratywnym, jak sugerują Bobson i inni w dokumentacji klasy lub członka, ale w kodzie nie ma nic złego w byciu mniej formalnym. W rzeczywistości czasami nieformalny komentarz jest bardziej skuteczny w wyjaśnieniu, dlaczego coś jest don, niż pełna ekspozycja w języku angielskim.

Oto próbka, która moim zdaniem ilustruje tę kwestię.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Innym pomysłem do rozważenia byłby dobrze spreparowany test jednostkowy, który pokazuje, dlaczego kod działa tak, jak działa zamiast pisania komentarza opisowego. Ma to kilka zalet w porównaniu z pisaniem komentarzy:

1. Komentarze nie zawsze zmieniają się po zmianie kodu, co może później prowadzić do zamieszania.

2. Testy jednostek dają opiekunowi łatwy sposób zabawy z kodem. Nauka nowej bazy kodu może być o wiele łatwiejsza, jeśli masz pojedyncze jednostki, które możesz rozbić, aby zaobserwować, jakie zmiany.

Chociaż ta droga wymaga wcześniejszej pracy, testy jednostkowe mogą być doskonałą formą dokumentacji.

Dobre komentarze są trudne do napisania, a nawet najlepsze komentarze są często trudne do odczytania i zrozumienia. Jeśli twój komentarz jest wystarczająco zwięzły, aby przyswoić sobie i wystarczająco precyzyjny, aby przekazać to, co muszę wiedzieć o kodzie, nie ma znaczenia, jakich zaimków używasz.

Nie chciałbym zniechęcać kogoś do komentowania ich kodu, ponieważ obawiają się o sprawę, czas i osobę zaimków.

Powodem, dla którego używam słowa „my” zamiast „ja” jest to, że dużo piszę w środowisku akademickim, gdzie „my” jest często preferowane.

Jest to zły styl, nawet dla prac naukowych, chyba że próbujesz ukryć, kto tak naprawdę zdecydował o tym dokładnie.

Co do twojego konkretnego pytania: nie zostawiłbym takiego komentarza, chyba że zaczyna się od:

// TODO: clean this up, ...

lub chyba że wyjaśnia coś bardzo ważnego, co może nie być tak jasne z kodu. W takim przypadku komentarz powinien być jak najkrótszy.