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

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 ?

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

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

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

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.

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.

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?

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.

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.

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