Komentarze kontroli wersji - czas przeszły lub teraźniejszy [zamknięte]

12

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.
Robert W.
źródło
27
Nie masz na myśli „kontroli wersji sprawdzającej komentarze”? Nigdy nie dodam komentarzy dokumentujących zmiany w rzeczywistym kodzie. Zaśmieca to.
JohnFx
1
Jestem naprawdę zdezorientowany - jeśli @JohnFx ma rację, to jest to zupełnie inne pytanie. Osobiście nie rozumiem, dlaczego @Robert nie mógł oznaczać komentarzy w kodzie źródłowym.
Armand,
FYI: Miałem na myśli
odprawę
Przepraszam - żeby wyjaśnić zamieszanie, miałem na myśli komentarze kontroli wersji, a raczej komentarze w kodzie źródłowym. Pytanie zostało zaktualizowane.
Robert W

Odpowiedzi:

19

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
    ....
}
Armand
źródło
NB: Myślę, że wszystkie komentarze w powyższym kodzie są zbędne, ale niekoniecznie byłyby to nietrywialne przykłady.
Armand,
7
Teraz pytanie się zmieniło, ta odpowiedź jest nieco nie na temat.
Armand,
22

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.

Tim
źródło
10

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

Berin Loritsch
źródło
3
+1, chociaż myślę, że komentarze kontroli wersji również powinny być w czasie przeszłym. :-)
Eric King,
Nie jest tak źle mieć osobny plik dziennika zmian; umieszczenie tam komentarzy do kwarantanny nie zaszkodzi zbytnio, ale rozpylanie ich na każdym pliku jest po prostu bolesnym hałasem.
Donal Fellows
Zaangażuj meesages może iść w obie strony. Zwykle patrzę na to, ponieważ była to obecna akcja z powodu popełnionego w tym czasie zatwierdzenia. Pod koniec dnia jest to obszar angielskiego, w którym prawdopodobnie nie można dzielić włosów. To nie jest tak, jak „Zjada, strzela i
odchodzi
10

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

mipadi
źródło
1
Zgadzam się, że na początku wydaje się to dziwne, a oglądanie go jako łatki jest zdecydowanie właściwą drogą. Jedną rzeczą, którą zrobiłem, jest recytowanie „Ta łatka” w mojej głowie przed odczytaniem mojej wiadomości zatwierdzenia. Jest to zmiana od zadawania sobie pytania „Co zrobiłem w tej łatce?” (Naprawiono błąd wątkowania) polegający na zadawaniu sobie pytania „Co zrobi ta łatka?” (Napraw błąd wątków).
Nick Knowlson,
5

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.

SOL__
źródło
2

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

Kenneth
źródło
1

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.


źródło
1

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

Garry Shutler
źródło
0

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”.

Macneil
źródło
0

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.

luis.espinal
źródło
0

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.>
    
kojiro
źródło