Chcę usłyszeć od ciebie wszelkie porady i doświadczenie w pisaniu komentarzy w twoim kodzie. Jak piszesz je w najłatwiejszy i najbardziej pouczający sposób? Jakie masz nawyki, komentując fragmenty kodu? Może jakieś egzotyczne rekomendacje?

Mam nadzieję, że to pytanie zgromadzi najciekawsze porady i zalecenia dotyczące komentowania, coś przydatnego, z którego każdy może się uczyć.

OK, zacznę.

1. Zwykle nie używam /* */komentarzy, nawet jeśli muszę komentować wiele wierszy.

   Zalety : kod wygląda wizualnie lepiej niż po zmieszaniu takiej składni z komentarzami jednowierszowymi. Większość IDE ma możliwość komentowania zaznaczonego tekstu i zwykle robi to przy użyciu składni jednowierszowej.

   Wady : Trudno edytować taki kod bez IDE.

2. Umieść „kropkę” na końcu każdego gotowego komentarza.

   Na przykład:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Zalety : umieść „kropkę” tylko w komentarzach, które ukończyłeś. Czasami możesz napisać informacje czasowe, więc brak „kropki” powie Ci, że chcesz wrócić i dodać dodatkowy tekst do tego komentarza.

3. Wyrównaj tekst w wyliczeniach, parametrach komentowania itp.

   Na przykład:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Zalety : Po prostu wygląda lepiej i wizualnie łatwiej znaleźć to, czego potrzebujesz.

   Wady : spędzanie czasu na wyrównanie i trudniejsze do edycji.

4. Napisz tekst w komentarzu, którego nie można uzyskać analizując kod.

   Na przykład głupi komentarz:

   //Apply style.
   Apply(style);
   

   Zalety : Będziesz miał jasny i mały kod z tylko użytecznymi informacjami w komentarzach.

Niektóre z poniższych stwierdzeń są dość osobiste, choć z pewnym uzasadnieniem, i tak mają być.

Rodzaje komentarzy

W krótkiej wersji ... Używam komentarzy do:

• końcowe komentarze wyjaśniające pola w strukturach danych (poza tymi tak naprawdę nie używam komentarzy jednowierszowych)
• wyjątkowe lub zorientowane na cel wieloliniowe komentarze powyżej bloków
• publiczna dokumentacja użytkownika i / lub programisty wygenerowana ze źródła

Przeczytaj poniżej, aby poznać szczegóły i (być może niejasne) przyczyny.

Końcowe komentarze

W zależności od języka, korzystając z komentarzy jednowierszowych lub wieloliniowych. Dlaczego to zależy? To tylko kwestia standaryzacji. Kiedy piszę kod C, domyślnie preferuję staroświecki kod ANSI C89, więc wolę zawsze mieć /* comments */.

Dlatego miałbym to najczęściej w C, a czasami (w zależności od stylu bazy kodu) dla języków o składni podobnej do C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs jest miły i robi to dla mnie M-;.

Jeśli język obsługuje komentarze jednowierszowe i nie jest oparty na języku C, będę bardziej skłonny do korzystania z komentarzy jednowierszowych. W przeciwnym razie obawiam się, że przyzwyczaiłem się. Co niekoniecznie jest złe, ponieważ zmusza mnie do zwięzłości.

Komentarze wieloliniowe

Nie zgadzam się z twoim przykazaniem, używając komentarzy jednowierszowych, ponieważ jest to bardziej atrakcyjne wizualnie. Używam tego:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Lub to (ale już nie tak często, z wyjątkiem osobistej bazy kodu lub głównie informacji o prawach autorskich - jest to dla mnie historyczne i pochodzi z mojego wykształcenia. Niestety, większość IDE spieprzyło to podczas korzystania z automatycznego formatowania) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Jeśli to naprawdę konieczne, to komentowałbym inline, używając tego, co wspomniałem wcześniej, dla końcowych komentarzy, jeśli sensowne jest użycie go w końcowej pozycji. Na bardzo szczególny przypadek powrotnej, na przykład, albo udokumentować switch„s casewypowiedzi (rzadko, nie używam przełączyć się często), lub gdy dokument oddziały w if ... elseprzepływ sterowania. Jeśli to nie jeden z nich, zwykle blok komentarza poza zakresem opisujący kroki funkcji / metody / bloku ma dla mnie większy sens.

Używam ich bardzo wyjątkowo, z wyjątkiem kodowania w języku bez obsługi komentarzy do dokumentacji (patrz poniżej); w takim przypadku stają się bardziej rozpowszechnione. Ale w ogólnym przypadku tak naprawdę służy tylko do dokumentowania rzeczy, które są przeznaczone dla innych programistów i są wewnętrznymi komentarzami, które naprawdę muszą się naprawdę wyróżnić. Na przykład, aby udokumentować obowiązkowy pusty blok, taki jak blok „wymuszony” catch:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Co jest już dla mnie brzydkie, ale w pewnych okolicznościach tolerowałbym.

Komentarze do dokumentacji

Javadoc i in.

Zwykle używam ich w metodach i klasach do dokumentowania wersji wprowadzających funkcję (lub zmieniających ją), szczególnie jeśli dotyczy to publicznego interfejsu API, i podam kilka przykładów (z wyraźnymi przypadkami wejścia i wyjścia oraz przypadkami specjalnymi). Chociaż w niektórych przypadkach lepiej jest udokumentować przypadek jednostkowy, testy jednostkowe niekoniecznie są czytelne dla człowieka (bez względu na to, jakiego używasz DSL).

Trochę robią mi błędy w dokumentowaniu pól / właściwości, ponieważ wolę końcowe komentarze do tego, a nie wszystkie ramy generowania dokumentacji obsługują końcowe komentarze do dokumentacji. Doxygen na przykład tak, ale JavaDoc nie, co oznacza, że ​​potrzebujesz najlepszego komentarza do wszystkich swoich pól. Mogę to jednak przetrwać, ponieważ linie Java i tak są przez większość czasu stosunkowo długie, więc komentarz końcowy przeraziłby mnie jednakowo, przedłużając linię poza mój próg tolerancji. Gdyby Javadoc zastanawiał się kiedyś nad tym, byłbym o wiele szczęśliwszy.

Skomentowany kod

Używam pojedynczej linii tylko z jednego powodu, w językach podobnych do C (z wyjątkiem kompilacji dla ścisłego C, gdzie tak naprawdę ich nie używam): do komentowania rzeczy podczas kodowania. Większość IDE będzie musiała przełączać się na komentarze jednowierszowe (wyrównane do wcięcia lub w kolumnie 0), i to pasuje do tego, który używa dla mnie przypadku. Użycie przełącznika do komentarzy wieloliniowych (lub wybranie pośrodku linii, w przypadku niektórych IDE) utrudni łatwe przełączanie między komentarzem / odkomentowaniem.

Ale ponieważ jestem przeciwny komentowanemu kodowi w SCM, zwykle trwa to bardzo krótko, ponieważ usunęłam komentowane fragmenty przed zatwierdzeniem. (Przeczytaj moją odpowiedź na to pytanie na temat „edytowanych przez komentarze i SCM” )

Style komentarzy

Zwykle piszę:

• uzupełnij zdania poprawną gramatyką (w tym interpunkcją) w komentarzach do dokumentacji, ponieważ powinny one być czytane później w dokumencie API lub nawet jako część wygenerowanego podręcznika.
• dobrze sformatowane, ale bardziej luźne przy interpunkcji / wielkich literach dla bloków komentarzy zawierających wiele wierszy
• końcowe bloki bez interpunkcji (ze względu na miejsce i zwykle dlatego, że komentarz jest krótki, który brzmi bardziej jak wyrażenie w nawiasie)

Uwaga na temat programowania czytania i pisania

Być może zechcesz zainteresować się programowaniem literackim , przedstawionym w tym artykule przez Donalda Knutha .

Umiejętny paradygmat programowania [...] stanowi odejście od pisania programów w sposób i w kolejności narzuconej przez komputer, a zamiast tego umożliwia programistom tworzenie programów w kolejności wymaganej logiką i przepływem ich myśli. 2 Programy literackie są pisane jako nieprzerwana ekspozycja logiki w zwykłym ludzkim języku, podobnie jak tekst eseju [...].

Literackie narzędzia programistyczne są używane do uzyskania dwóch reprezentacji z literackiego pliku źródłowego: jeden odpowiedni do dalszej kompilacji lub wykonania przez komputer, „splątany” kod, a drugi do przeglądania jako sformatowana dokumentacja, o której mówi się, że jest „tkana” z piśmienne źródło.

Na marginesie i przykład: Framework JavaScript underscore.js , pomimo nieprzestrzegania mojego stylu komentowania, jest całkiem dobrym przykładem dobrze napisanej bazy kodu i dobrze uformowanego źródła z adnotacjami - choć może nie najlepiej użyć go jako referencja API).

To są osobiste konwencje. Tak, mogę być dziwny (i ty też możesz być). Jest w porządku, pod warunkiem, że przestrzegasz konwencji kodu twojego zespołu podczas pracy z rówieśnikami lub nie atakujesz radykalnie ich preferencji i nie żyjesz razem . Jest to część twojego stylu i powinieneś znaleźć cienką linię między rozwijaniem stylu kodowania, który definiuje cię jako programistę (lub jako wyznawcę szkoły myśli lub organizacji, z którą masz połączenie), a przestrzeganiem konwencji grupy o spójności .

Kiedy poszedłem na uniwersytet, zawsze uczono mnie komentowania każdej linii kodu i nagłówka każdej metody. Został wbity / indoktrynowany w takim stopniu, że zrobiłeś to bez pytania. Będąc częścią kilku zespołów programistycznych Agile w różnych firmach, mogę powiedzieć, że mogę napisać komentarz raz na niebieskim księżycu.

Powód tego jest dwojaki, przede wszystkim nie powinniśmy już pisać długich monolitycznych metod, które wykonują 101 różnych rzeczy, nazwy klas, metod i zmiennych powinny być samok dokumentujące. Weź przykładową metodę logowania.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Można to przepisać na coś, co jest o wiele bardziej czytelne i być może wielokrotnego użytku:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Z metody logowania wyraźnie widać, co się dzieje. Możesz uznać to za dodatkową pracę, ale twoje metody są małe i mają tylko jedną pracę. Ponadto nazwy metod są opisowe, więc nie ma potrzeby pisania komentarzy w nagłówkach metod. Jeśli skończysz ze zbyt wieloma metodami, oznacza to, że powiązane metody powinny zostać ponownie uwzględnione w innym obiekcie, takim jak UserAuthenticationService, pamiętaj, że obiekt powinien mieć tylko jedno zadanie.

Po drugie, każdy fragment kodu, który piszesz, w tym komentarze, musi zostać zachowany, im więcej komentarzy masz, tym więcej jest do utrzymania. Jeśli zmienisz nazwę klasy lub zmiennej, otrzymasz błąd kompilacji, ale jeśli zmienisz sposób działania sekcji kodu lub usuniesz ją i nie zaktualizujesz żadnych powiązanych komentarzy, nie wystąpi błąd kompilacji, a komentarze będą się zawieszać, powodując zamieszanie .

Jeśli piszesz API, to uważam, że wszelkie publiczne interfejsy, klasy, wyliczenia powinny mieć dobrze napisane komentarze do nagłówków do dokumentacji.

Skoncentruj się mniej na formacie, a bardziej na treści. Na przykład komentarze w twoim przykładzie nie mówią mi nic nowego. Są gorsze niż bezwartościowe, ponieważ utrudniają czytanie kodu, a takie komentarze w najlepszym razie są niejasnym odniesieniem do tego, co pierwotny programista myślał, że robił w czasie, gdy go pisał. Widzę na przykładzie kodu, że stosujesz styl „Apply (Style)”, mogę odczytać źródło. Nie umiem czytać w twoich myślach - dlaczego to robisz, tak powinien mi powiedzieć komentarz. np. zamiast

//Apply style.

Apply(style);

powinno być

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

Większość z nas pracuje w zespołach na istniejącym kodzie, formatuje tak, jak robi to reszta zespołu, tak jak to już jest robione. Spójność jest o wiele ważniejsza niż ładna.

W miarę możliwości napisz swój kod, aby komentarze były całkowicie obce. Dodawaj komentarze tylko wtedy, gdy kodu nie można napisać w taki sposób, aby uczynić ważną koncepcję oczywistą.

Osobiście wolę, aby było to naprawdę proste. Unikam wszelkiego rodzaju wymyślnego formatowania. Głównym tego powodem jest to, że uważam, że kod źródłowy powinien być wygodnie edytowalny nawet w najprostszym edytorze tekstu. Nigdy też nie zawijam na stałe akapitów tekstu, ale zamiast tego pozwalam edytorowi na miękkie zawijanie (bez dodawania nowych linii).

Często widzę takie komentarze, a niektóre narzędzia automatycznie generują je w ten sposób:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Dwie linie mniej:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDE i edytory, nieznacznie powyżej poziomu notatnika, są w stanie wykrywać komentarze i drukować je w innym kolorze. Nie ma potrzeby ozdabiania początku linii gwiazdkami.

Oszczędzasz nawet niektóre bajty, jeśli używasz tabulacji do wcięcia.

Jeśli nie korzystasz z wyrafinowanego edytora, który renderuje komentarz w tonie szarym, duża liczba gwiazdek będzie działać jako podkreślenie i przyciągnie twoją uwagę, co jest przeciwieństwem właściwego postępowania: pozostać w tyle.

Oto „anty-wzorzec”, który znalazłem w całym kodzie mojej pracy: Wykorzystanie komentarzy jako „dziennika zmian”; po to jest dziennik w twoim systemie kontroli wersji. Kod jest zaśmiecony takimi rzeczami jak:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

i zwykle często zawiera stary kod, który został skomentowany (to znowu jest punkt systemu VCS, więc nie musi być w kodzie po napisaniu nowego kodu). Należy również unikać powtarzających się komentarzy, takich jak „Dlaczego tego potrzebujemy?” lub jeszcze gorzej: „Prawdopodobnie należy zmienić nazwę” (ponieważ istnieją wyrafinowane narzędzia do zmiany nazwy, więc w czasie, gdy napisanie tego komentarza zajęło Ci zmianę nazwy). Ponownie zajmuję się tymi komentarzami regularnie, zgodnie z następującymi zasadami:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Wybierz system dokumentacji, taki jak doxygen, i trzymaj się go. Kontynuuj sprawdzanie wyprodukowanych dokumentów.
2. Spróbuj wyobrazić sobie kogoś nowego w bazie kodu i czytającego twoje dokumenty, czy może zacząć od tego? Stażyści są w tym naprawdę dobrzy, usiądź na nowej z istniejącą bazą doktorów i prostym zadaniem i zobacz, jak daleko się posuną, jeśli się potkną, z całą pewnością wszystko, co im powiedziałeś, aby znów jechali, trafi do dokumentacji.
3. Spraw, aby komentarze w dokumentacji były punktem kontrolnym w procesach recenzji.

Czytniki kodów zazwyczaj próbują odpowiedzieć na trzy pytania:

1. Czym zajmuje się ta klasa lub funkcja? Jeśli trudno jest odpowiedzieć, to robi za dużo. Kod, który trudno jest udokumentować, jest zwykle po prostu zły.
2. Jak z tego korzystać? Przykład może być wystarczająco dobry.
3. Ten kod jest zaskakujący. Dlaczego to zrobiłeś? Najbardziej prawdopodobne odpowiedzi: obejście błędu w komponentach innych firm, ponieważ oczywista technika okazała się zbyt wolna

Wszystko inne powinno być wyrażone w kodzie. Podobnie jak pisanie prozy, jest to sztuka i wymaga dużo praktyki. Jedynym sposobem, aby dowiedzieć się, czy Twój kod jest zrozumiały, jest zachęcenie kogoś do jego przeczytania. Kiedy czegoś nie rozumieją, nie tłumacz tego słownie. Popraw kod. Dodaj komentarze w ostateczności.

Jeśli zobaczę „podwójną długość”, zapytam „Jaka jest jednostka miary?” Nie dodawaj komentarza. Zmień nazwę zmiennej. Jeśli widzę blok kodu i mówię „co to robi?”, Nie dodawaj komentarza. Wyodrębnij funkcję o znaczącej nazwie. Jeśli nie możesz wyodrębnić funkcji, ponieważ wymagałaby ona 17 argumentów, popraw kod.