Jakie są twoje przemyślenia na temat okresów / pełnych postojów w komentarzach do kodu? [Zamknięte]

27

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 ?

Mosze
źródło
2
Czasami robię, a czasem nie. To zależy od komentarzy i tego, co ułatwia czytanie.
Tim

Odpowiedzi:

29

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.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}
mojuba
źródło
4
+1. To bardzo przypomina mój styl komentowania, co dało mi fałszywe deja vu. :)
Tabele Bobby
26
Nie, kropka służy do oznaczenia końca zdania. Nie ma znaczenia, czy masz jeden, czy kilka.
Rook
2
<joke> Czy nie byłoby lepiej sprawdzić przekroczenie granic wewnętrznych? </joke>
Dan Rosenstark
2
@ Yar: średnia jest zawsze pomiędzy aib, które z definicji zawsze mieszczą się w granicach, prawda? ;)
mojuba,
8
Wszystkie moje ciągi są zakończone zerem, więc właściwy komentarz powinien zawsze kończyć się na „\ 0”. Nie chcesz, żeby następny facet patrząc na twój kod czytał poza końcem jego umysłu, prawda?
CodexArcanum
26

Tak, ponieważ komentarze są w języku angielskim, a poprawny angielski używa interpunkcji.

Dominique McDonnell
źródło
2
A co z wiadomościami tekstowymi?
Moshe,
4
@Moshe, wiadomości tekstowe nie są poprawnym angielskim.
Dominique McDonnell,
8
Niezbyt poprawny angielski, ale nadal używam w nich interpunkcji. Interpunkcja ma na celu pomóc czytelnikowi dokładnie określić, co zamierzał autor - dotyczy to dowolnego języka, IMHO.
cjmUK
@cjmUK, Lol, tak i ja też. Myślałem, że Mosze miał na myśli powód, dla którego nie będziemy używać interpunkcji, ponieważ regularnie otrzymuję wiadomości typu „ten wd b gr8 cu tam pa”, które prowadzą mnie do ściany
Dominique McDonnell
I nu wot
you
17

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

Wieża
źródło
Mój przyjaciel nigdy nie ujmuje słów w e-mailach ... ponieważ są one dostępne w Internecie. Dla mnie jest w porządku, jeśli dostosujesz swoje pisanie do ograniczeń technicznych, takich jak SMS, ale czym różnią się wiadomości e-mail lub kod źródłowy od tekstu w listach i książkach?
LennyProgrammers,
1
@ Lenny222 - Nie jestem pewien, o co tutaj pytasz. E-maile powinny być pisane jak zwykły tekst; jak piszesz list, jak mówisz. Jak są one faktycznie napisane (i SMS-y, och chłopcze, nie zaczynaj od SMS-ów :) Kod źródłowy nie podlega tym samym regułom, co zwykły tekst, ponieważ ma własne reguły składniowe.
Rook
2
Dla mnie komentarze do kodu źródłowego powinny być czytane przez ludzi. Dlaczego miałoby to wpływać na to, czy niektóre informacje znajdują się w osobnym dokumencie specyfikacji, czy są osadzone w komentarzu do kodu źródłowego?
LennyProgrammers,
@ Lenny222 - Coś mi się przydarzyło, żeby nie było między nami nieporozumień. Mówimy teraz o kodzie źródłowym lub wpisanych w nim komentarzach? Jeśli to drugi przypadek, przepraszam, bo źle cię zrozumiałem. W takim przypadku obowiązują te same zasady, co w przypadku zwykłego tekstu (w przypadku komentarzy). W rzeczywistym kodzie źródłowym (tym, który jest odczytywany przez kompilator / interpreter), nie widzę, jak mogłyby obowiązywać te same reguły.
Rook
1
Tak, myślę, że zgadzamy się ze sobą bez wiedzy. ;)
LennyProgrammers
9

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.

szybko
źródło
1
Okresy dotyczą końca zdania. Komentarze niekoniecznie są pełnymi zdaniami.
John B. Lambe,
Ogólnie komentarze powinny być zdaniami. Jeśli nie, powinienem zapytać, dlaczego nie. Jeśli twoje komentarze są tak krótkie, że nie są zdaniami, to może są oczywiste, a zatem zbędne?
szybko_niedz.
5

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.

Adam Lear
źródło
Jeśli używasz znaków zapytania, czy rozumiesz swój własny kod?
Moshe,
@Moshe: Zazwyczaj są w TODO, gdy jeszcze nie rozumiem w pełni własnego kodu.
Adam Lear
2
@Moshe - Dlaczego komentarze nie mogą zawierać pytań? Pytania mogą być retoryczne. W rzeczywistości często my? w moich komentarzach - gdy opisuję kod warunkowy, a nie suche wyjaśnienie logiki, często łatwiej jest opisać logikę jako pytanie. Np. „Czy kryteria kwalifikacyjne zostały spełnione? Jeśli Nie, wyświetl ostrzeżenie dla użytkownika.”
cjmUK
1
W pracy z dużymi projektami i wieloma współpracownikami często uważam te pytania za najważniejsze.
LennyProgrammers,
3

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:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

i

    // This code really sucks!

Z drugiej strony znaki zapytania są czasem bardzo przydatne:

    // TODO: What does Crojpler.bway() actually do?
Dan Rosenstark
źródło
1

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:

// check for vk_enter

Dokumentacja metody „właściwej”:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.
Stoły Bobby'ego
źródło
Programista .NET, co? ;-)
Moshe
@Moshe: Java faktycznie. Jest to kod z bardzo dużego i złożonego apletu, w zasadzie podobnego do aplikacji Swing na komputery stacjonarne, z tym wyjątkiem, że działa w przeglądarce. :)
Tabele Bobby
Myślałem, że MDI to termin .NET.
Moshe,
@Moshe: Nie, to ogólne ( en.wikipedia.org/wiki/Multiple_document_interface ).
Tabele Bobby
1

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
1
A co z drugą osobą?
daviewales
0

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

Matt DiTrolio
źródło