Widziałem to w SO Tavern , więc zamieszczam pytanie tutaj. Pomyślałem, że to interesujące pytanie. (Oczywiście, że nie należy do SO, ale myślę, że tutaj jest OK.)
Czy dodajesz kropki (lub, jak napisał PO, „kropki” w komentarzach do kodu?
Aby zachować aktualność, dlaczego ?
Odpowiedzi:
Kropka służy do kończenia zdań, ale jeśli komentarz składa się tylko z jednego zdania otoczonego kodem, moim zdaniem kropka nie jest konieczna. Czasami nawet nie używam pierwszej litery. Z drugiej strony szczegółowy komentarz wieloliniowy wymaga pełnej interpunkcji.
źródło
Tak, ponieważ komentarze są w języku angielskim, a poprawny angielski używa interpunkcji.
źródło
Czy dodajesz kropki (lub, jak napisał PO, „kropki” w komentarzach do kodu?
Aby zachować aktualność, dlaczego?
Z tego samego powodu dodaję je podczas pisania „normalnego” tekstu - są one częścią języka pisania i nie powinno być w nich nic specjalnego. Używam ich na równi podczas pisania komentarzy w jednym zdaniu (jednej linii), a także w całych akapitach.
Kod źródłowy nie jest zwykłym tekstem, dlatego używamy do tego różnych reguł. Prosty ;-)
źródło
Jeśli napiszesz komentarze, możesz mieć nadzieję, że są napisane po angielsku. W takim przypadku należy odpowiednio interpunkować. Postępowanie inaczej byłoby leniwe.
źródło
Jeśli piszę pełne zdanie (lub więcej), to tak. Jeśli nie, to czasami nie, ale zwykle nadal tak.
Czasem też wariuję i używam wykrzykników, znaków zapytania itp.;)
Co do tego, częściowo dlatego, że jestem po prostu taki szczególny, a częściowo dlatego, że uważam, że odpowiednia interpunkcja może dodać dużo przejrzystości.
źródło
Inne odpowiedzi i ich popularność wyraźnie pokazują, że kropki są dobrze doceniane w dłuższych komentarzach i prawdopodobnie można ich uniknąć w linijkach.
Inną kwestią, która może być istotna, jest unikanie wykrzykników, zwłaszcza wielokrotności . Przykład:
i
Z drugiej strony znaki zapytania są czasem bardzo przydatne:
źródło
To zależy. Jeśli napiszę duży, poprawny akapit wyjaśniający, co robi blok kodu, to interpunkuję go poprawnie, jak każdy inny poprawny tekst. OTOH, kiedy tylko komentuję pojedynczy wiersz kodu, to nie robię tego.
Czemu? - Podobne do tego, dlaczego piszę e-maile, używając właściwego pisania, podczas gdy w wiadomościach SMS mogę używać krótszych zdań. W jednym przypadku siedzę, aby napisać odpowiedni blok tekstu, więc po prostu automatycznie „rób to poprawnie”, w drugim przypadku jest to tylko krótka notatka, aby uzyskać punkt.
Prawdziwe przykłady z mojego kodu:
Krótki komentarz do notatki:
Dokumentacja metody „właściwej”:
źródło
Tak, myślę, że w ten sposób tworzysz dobrą konwencję kodowania, a także tworzy czytelny kod dla trzeciej osoby przeglądającej kod.
źródło
Zawsze będę właściwie pisać dużymi literami i interpunkcyjnie podczas tworzenia komentarzy XML, które powinny być widoczne w IntelliSense i naszej wygenerowanej dokumentacji . Są to znacznie bardziej formalne konstrukcje i powinny być traktowane jako takie.
Komentarze widoczne w treści bloku kodu powinny być jednak możliwie jak najbardziej jasne. Od programisty zależy, jak to osiągną.
źródło