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ę.
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.
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.
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.
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.
źródło
:3,7 Align //
aby wyrównać komentarze w wierszach 3-7.Odpowiedzi:
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:
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:
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:
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) :
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
„scase
wypowiedzi (rzadko, nie używam przełączyć się często), lub gdy dokument oddziały wif ... else
przepł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
: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ę:
Uwaga na temat programowania czytania i pisania
Być może zechcesz zainteresować się programowaniem literackim , przedstawionym w tym artykule przez Donalda Knutha .
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 .
źródło
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.
Można to przepisać na coś, co jest o wiele bardziej czytelne i być może wielokrotnego użytku:
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.
źródło
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.
źródło
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ą.
źródło
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).
źródło
Często widzę takie komentarze, a niektóre narzędzia automatycznie generują je w ten sposób:
Dwie linie mniej:
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.
źródło
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:
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:
źródło
źródło
Czytniki kodów zazwyczaj próbują odpowiedzieć na trzy pytania:
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.
źródło