W przypadku komentarzy kontroli wersji, co robią / polecają inni użytkownicy - czas przeszły czy teraźniejszy?

To znaczy

• Zmieniono x na y.
• lub
• Zmieniam x na y.

Komentarze należy czytać w kontekście, więc:

Obecny

W przypadku komentarzy źródłowych powyżej metody lub przed wystąpieniem jakiegoś zachowania:

// This function does X
function doX() { ... }

Przeszłość

W przypadku komentarzy źródłowych po pewnym zachowaniu

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

I dla wiadomości zatwierdzania

funkcja X została zmieniona

Mieszany przykład:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Przeszłość - ponieważ każdy, kto ją przeczyta w przyszłości, odniesie się do aktu zmiany, jaki miał miejsce w przeszłości.

Sformułowanie czegoś jako „zmiana” oznacza, że ​​obecnie dokonujesz zmiany i że kod może nie zostać ukończony.

Uwaga: Osobiście umieszczam komentarze dotyczące zmian tylko wtedy, gdy nastąpiła drastyczna zmiana.

Komentarze to rzeczy statyczne, dlatego powinny prezentować stan programu w obecnym stanie , a nie w zamierzonym stanie. Aby odpowiedzieć na konkretne pytanie, właściwsze byłoby użycie czasu przeszłego .

Ten rodzaj komentarza jest jednak bardziej odpowiedni dla twojego systemu kontroli wersji. Kontrola wersji wykonuje znacznie lepsze śledzenie zmian niż ręczne komentarze. W przypadku systemów kontroli wersji bardziej odpowiednie jest dokumentowanie w czasie teraźniejszym, ponieważ komentarze te obowiązują w momencie zatwierdzenia zmiany. Ale albo zadziała.

Gorąco polecam, aby jedynymi komentarzami w kodzie były informacje wymagane do zrozumienia samego kodu - cel, logika biznesowa i wyjątkowe przypadki. Pozostaw dokumentację zestawu zmian do systemu kontroli wersji. Jeśli nie korzystasz z VCS, zacznij teraz. Istnieje kilka wysokiej jakości VCS, które są bezpłatne (Subversion, Mercurial, Git itp.).

Używam czasu teraźniejszego rozkazującego, więc coś w stylu:

Zmień „x” na „y”

Jest to zalecane przez programistów Git:

• ciało powinno dostarczyć sensownego komunikatu zatwierdzenia, który:
  • używa czasu nadrzędnego, czasu teraźniejszego: „zmiana”, a nie „zmiana” lub „zmiany”.

Na początku może się to wydawać nieco dziwne, ale jeśli myślisz o zatwierdzeniu jako łatce, która coś robi, ma to większy sens. (Jest to szczególnie prawdziwe w DVCS, takich jak Git, w którym pobierasz zestawy zmian od innych osób, które działają na Twoim repozytorium.)

To naprawdę nie ma znaczenia; Myślę, że to osobisty styl i preferencje. Jeśli chodzi o pisanie prawie wszystkiego, po prostu bądź zgodny ze sobą i innymi komentarzami.

Komentarze do kodu powinny być czytelne.

Jeśli czytasz ten kod mówiąc do siebie „Ten kod jest robić X”, to powinieneś napisać komentarz w czasie teraźniejszym, gdyż jest to prawdopodobne, jak ktoś czyta kod w tym czasie będą również myśleć. Jeśli z drugiej strony myślałeś w pewnym momencie „Ten kod zrobił X”, to powinno być po czasie przeszłym. Ostatecznie sprowadza się to do osobistych preferencji, chyba że z jakiegoś powodu jesteś pod wskazówkami, jak skomentować swój kod (np. W przypadku projektu zespołowego lub zajęć itp.).

Jeśli używasz git, konwencja polega na użyciu czasu teraźniejszego, ponieważ komunikaty zatwierdzania generowane za pomocą narzędzi git (np. Scalanie) używają czasu teraźniejszego.

Powinieneś użyć czasu przeszłego.

Powodem, dla którego odpowiadasz na pytanie, co osiągnęło to zatwierdzenie? Pomyśl o tym, jak mówisz VCS o tym, co zrobiłeś:

Commit 123
Zmieniono XYZ na ABC

Aby podać przykłady, użycie czasu przyszłego sprawia, że ​​brzmi to tak, jakbyś poprosił o to kogoś innego:

Zatwierdź 123
Zmień XYZ, aby zrobić ABC

i używanie czasu teraźniejszego brzmi, jakbyś był w połowie:

Zatwierdź 123
Zmiana XYZ na ABC

Użyj czasu teraźniejszego: „Zmień X na Y”, prawie tak, jakby to był element na czystej liście DO ZROBIENIA.

Ogólnie rzecz biorąc, podobnie jak scenariusz, unikaj czasowników takich jak „być” i „jest”. Na przykład, to nie „idzie”, ale „idzie”.

Ale w tym konkretnym przykładzie - jeśli mówisz o komentarzach do kodu, a nie komentarzach do odprawy - uważam, że „Zmień X na Y” jest okropnym komentarzem. Nie dodaje żadnych nowych informacji, a jeśli kod miałby ulec zmianie, może nawet być niepoprawny. Lepiej jest wyodrębnić kod do metody (lub klasy), a następnie udokumentować tę metodę zamiast tego. Jeśli jest wystarczająco jasny, wystarczy dobra nazwa metody.

Mówiąc o tym, do dokumentowania metod możesz użyć czasu przyszłego, np .: „Jeśli podana liczba jest ujemna, abszwróci wielkość liczby”.

Komentarze są (lub powinny być), jak każde napisane, wyrażeniem czegoś i powinny po prostu przestrzegać tych samych zasad w językach naturalnych (biorąc pod uwagę skróty i skróty charakterystyczne dla dokumentowanej sytuacji lub artefaktu.

Komentarze do czasu teraźniejszego ( .ie „zmienia się” lub „zmienia się” ) wskazują, że jakoś wpływa to na dane przetwarzane przez udokumentowany algorytm. Oznacza to, co robi kod lub co dzieje się z przetwarzanymi danymi.

Komentarze w czasie przeszłym powinny wskazywać na stwierdzenie, warunek wstępny lub warunek wstępny czegoś, co wydarzyło się przed punktem, w którym komentarz się znajduje. Na przykład:

Dane wejściowe zostały już sprawdzone przed wprowadzeniem tego bloku kodu

lub

Dane zostały zapisane do pliku na końcu wykonywanego kodu

Komentarze w czasie przeszłym mogą również wyjaśniać, dlaczego coś się robi ( ta funkcja wykonuje polecenia X i Y, aby rozwiązać problem ze starszą bazą danych ).

Komentarze w czasie przeszłym wskazujące na zmianę samego kodu (.ie. X zmieniono na Y ) nie powinny istnieć w kodzie. Powinny one istnieć jako komentarze do wersji w repozytorium kodu źródłowego.

Komentarze w przyszłości powinny wskazywać na warunek, który należy spełnić lub rozwiązać, ale z powodu X lub Y nie jest on teraz wykonywany. Na przykład:

Kiedy w końcu przeprowadzimy migrację bazy danych, będziemy musieli zmienić tę logikę

lub

DO ZROBIENIA: jak najszybciej, ponownie sprawdź poprawność danych wejściowych - może się nie powieść w przypadku danych wejściowych typu X lub Y, może wymagać ogromnych zmian, których nie można teraz wdrożyć.

W przypadku późniejszych komentarzy typu TODO powinna istnieć inna dokumentacja, aby upewnić się, że takie zmiany rzeczywiście nastąpiły. Ostatnią rzeczą, jakiej chcesz, to TODO utracone w czasie i przestrzeni: P

Weź to z odrobiną soli, ale zazwyczaj są to zasady, których zwykle przestrzegam, gdy piszę własne komentarze.

Komentowanie dotyczy komunikowania się z ludźmi, więc chociaż ważna jest konsekwencja, ważne jest, aby nie zagłębiać się w zasady, gdy same zasady utrudniają dobrą komunikację. To powiedziawszy, używam następujących pseudo-standardów:

• Komentarze opisujące pożądane zachowanie przybierają formę czasu teraźniejszego.

  // Calculate the width of the curve at x height.
  

• Użyj zestawu słów kluczowych z wielkimi literami, aby opisać typowe motywy w kodowaniu (i ułatwić wyszukiwanie):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>