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.
comments
source-code
Robert W.
źródło
źródło
Odpowiedzi:
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:
Przeszłość
W przypadku komentarzy źródłowych po pewnym zachowaniu
I dla wiadomości zatwierdzania
Mieszany przykład:
źródło
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.
źródło
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.).
źródło
Używam czasu teraźniejszego rozkazującego, więc coś w stylu:
Jest to zalecane przez programistów Git:
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.)
źródło
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.
źródło
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.).
źródło
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
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ś:
Aby podać przykłady, użycie czasu przyszłego sprawia, że brzmi to tak, jakbyś poprosił o to kogoś innego:
i używanie czasu teraźniejszego brzmi, jakbyś był w połowie:
źródło
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,
abs
zwróci wielkość liczby”.źródło
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.
źródło
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.
Użyj zestawu słów kluczowych z wielkimi literami, aby opisać typowe motywy w kodowaniu (i ułatwić wyszukiwanie):
źródło