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

41

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:

Użyj „My”: Powodem tego jest ...
Użyj „I”: Powodem, dla którego to robię jest ...
Użyj mojego imienia: Powodem [my name]tego jest ...
Głos pasywny: Powodem tego jest ...
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.

documentation

— Alan Turing
źródło

Myślę, że to zależy od osobistych preferencji. Nie widzę żadnego powodu, dla którego jedno byłoby bardziej jasne niż drugie w ogóle.

— ConditionRacer

6

Co powiesz na # 5: „When in the human events ...”;)

— waxwing

8

„Cztery punkty i siedem sekund temu nasi przodkowie nauczyli się, że foo musi zostać zablokowane, a nasze siły zostaną pokonane przez NULL”

— Philip

Silnie powiązane z angielskim. SE: Dlaczego programiści zawsze używają słowa „my”, skoro tak naprawdę mają na myśli „ja” lub „ty”? (Który niestety został zamknięty)

— Izkata

2

Dlaczego nie powiesz This code was written like this because...? (Pasywny głos)

— Alvin Wong,

77

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.

— Bobson
źródło

czy miałbyś coś przeciwko opracowaniu dlaczego? Bez wyjaśnienia ta odpowiedź bardziej przypomina zwykłą opinię, nieco sprzeczną z wytycznymi : „... Opinia nie jest zła, o ile jest poparta czymś innym niż„ ponieważ jestem ekspertem ” lub „ponieważ tak powiedziałem” lub „tylko dlatego, że”. Wykorzystaj swoje szczególne doświadczenia, aby poprzeć swoje opinie, jak wyżej, lub wskaż jakieś badania przeprowadzone w sieci lub w innym miejscu, które dostarczają dowodów na poparcie twoich roszczeń ... ”

— gnat

15

@gnat „Powód, dla którego to zrobiono” nie dodaje niczego do wyjaśnienia. Komentarze powinny zawierać tylko tyle tekstu, aby uzyskać sens i nie więcej. Pomiń subtelności, preambuły i inne teksty wypełniające.

— David Harkness

@gnat - Właśnie skończyłem dodawać więcej, kiedy zobaczyłem twój komentarz.

— Bobson,

1

Myślę, że mój przykład był zbyt uproszczony, ponieważ rzeczywiście „powód, dla którego to zrobiono” nic nie dodaje. Ale zdarzają się sytuacje, w których trudna sytuacja wymaga pewnych wyjaśnień, i w takim przypadku uważam, że bardziej naturalne jest użycie „my” lub „ja”, podobnie jak kilkakrotnie użyłem „ja” w tym komentarzu. Ale myślę, że twoja odpowiedź jest jasna w duchu: „deklaratywny” sugeruje: używaj najmniejszej liczby słów, które jasno wskazują punkt.

— Alan Turing

7

Czytam //jak becausew większości przypadków.

— Ilmo Euro

23

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.

— Karl Bielefeldt
źródło

4

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);
    ...
}

— pswg
źródło

4

Uwaga dodatkowa: SanitizeDatapowinien zwrócić a SafeComplexObject. ;)

— Jon Purdy,

Zgadzam się, ale wolę dosłowne (a nie metaforyczne) komentarze, szczególnie jeśli mogą istnieć programiści z różnych środowisk językowych.

— John B. Lambe,

2

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:

Komentarze nie zawsze zmieniają się po zmianie kodu, co może później prowadzić do zamieszania.
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.

— śmiertelnik
źródło

1

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.

— John M. Gant
źródło

Pozwól, że wyjaśnię: w przypadku komentarzy, które staną się częścią formalnej dokumentacji, bardziej formalny ton jest odpowiedni, a „ja” i „my” najlepiej unikać. Z tą odpowiedzią miałem na myśli sporadyczny komentarz wyjaśniający, na przykład, gdy zrobiłeś coś, co będzie wyglądać źle dla następnego faceta. W tych przypadkach, gdzie tylko ludzie, którzy pracują w tej samej bazie kodu będzie kiedykolwiek go zobaczyć, mówię zrobić cokolwiek przekaże swój sens najbardziej wyraźnie, nawet jeśli jest to I wrote the code this way because...albo what we really need here is.... W takich przypadkach wyraźny komentarz jest ważniejszy niż surowy styl.

— John M Gant,

1

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.

— BЈовић
źródło