Wskazówki dotyczące kodu źródłowego komentarzy i najlepszych praktyk

Programiści, którzy spędzili jakiś czas na dużych projektach, rozumieją znaczenie komentarzy do kodu. Kiedy budujesz wiele funkcji w tej samej aplikacji, sprawy stają się skomplikowane. Jest tak wiele bitów danych, w tym funkcje, odwołania do zmiennych, wartości zwracane, parametry… jak można się spodziewać?

Nie powinno dziwić, że komentowanie kodu jest niezbędne, zarówno dla projektów indywidualnych, jak i zespołowych. Jednak wielu programistów nie wie, jak postępować w tym procesie. Przedstawiłem kilka moich własnych sztuczek tworzenie zgrabnych, sformatowanych komentarzy do kodu. Standardy i szablony komentarzy będą się różnić w zależności od twórców - ale ostatecznie należy dążyć do tego czyste i czytelne komentarze w celu dalszego wyjaśnienia mylących obszarów w kodzie.

Powinniśmy zacząć omawiać niektóre różnice w formatowaniu komentarzy. Zapewni to lepsze wyobrażenie o szczegółach, jakie można uzyskać dzięki kodowi projektu. Następnie przedstawię kilka konkretnych wskazówek i przykładów, które możesz zacząć używać od razu!

Style komentarza: przegląd

Należy zauważyć, że przedstawione pomysły są jedynie wytyczne w kierunku czystszych komentarzy. Poszczególne języki programowania nie określają wytycznych ani specyfikacji dotyczących konfiguracji dokumentacji.

Mając to na uwadze, współcześni programiści zgrupowali się, aby sformatować własny system komentowania kodu. Zaproponuję kilka stylów głównego nurtu i szczegółowo omówię ich cel.

Komentowanie inline

Praktycznie każdy język programowania oferuje komentarze wbudowane. Są one ograniczone do treści jednokreskowych i komentują tekst dopiero po pewnym momencie. Na przykład w C / C ++ zaczynasz taki komentarz:

// rozpocznij wyświetlanie zmiennej var myvar = 1;… 

Jest to idealne rozwiązanie do wpisywania kodu przez kilka sekund wyjaśnij prawdopodobnie mylącą funkcjonalność. Jeśli pracujesz z wieloma parametrami lub wywołaniami funkcji, możesz umieścić w pobliżu mnóstwo komentarzy wbudowanych. Ale najbardziej korzystne jest użycie proste wyjaśnienie małej funkcjonalności.

if (callAjax ($ params)) // pomyślnie uruchomił callAjax z parametrami użytkownika… kod

Uwaga przede wszystkim kod musiałby być na nowej linii po nawiasie otwierającym. W przeciwnym razie wszystko zostanie złapane w tej samej linii komentarza! Unikaj przesiadki ponieważ generalnie nie musisz widzieć komentarzy jednokreskowych na całej swojej stronie, ale szczególnie w przypadku mylących skrzyżowań w kodzie, są one znacznie łatwiejsze do upuszczenia w ostatniej chwili.

Bloki opisowe

Jeśli chcesz dołączyć duże wyjaśnienie, pojedynczy liner nie zadziała. W każdym obszarze programowania używane są wstępnie sformatowane szablony komentarzy. Bloki opisowe są szczególnie widoczne wokół funkcji i plików bibliotek. Za każdym razem, gdy konfigurujesz nową funkcję, dobrą praktyką jest dodaj blok opisowy nad deklaracją.

/ ** * @desc otwiera okno modalne, aby wyświetlić komunikat * @param string $ msg - wiadomość do wyświetlenia * @return bool - success or failure * / function modalPopup ($ msg) … 

Powyżej jest prosty przykład opisowego komentarza do funkcji. Napisałem funkcję przypuszczalnie w wywoływanym JavaScript modalPopup który przyjmuje pojedynczy parametr. W powyższych komentarzach użyłem składni podobnej do phpDocumentor, gdzie każda linia jest poprzedzona znakiem @ symbol, po którym następuje wybrany klucz. Nie wpłyną one w żaden sposób na twój kod, więc możesz pisać @opis zamiast @desc bez żadnych zmian.

Te małe klucze są rzeczywiście wywoływane tagi komentarzy które są mocno udokumentowane na stronie internetowej. Możesz tworzyć własne i używać ich w dowolny sposób w swoim kodzie. Uważam, że pomagają utrzymać wszystko tak płynące Potrafię szybko sprawdzić ważne informacje. Powinieneś również zauważyć, że użyłem / * * / format komentowania w stylu bloku. To zatrzyma wszystko dużo czystszy niż dodawanie podwójnego ukośnika zaczynającego się w każdym wierszu.

Komentarze grupy / klasy

Oprócz komentowania funkcji i pętli, obszary bloków nie są wykorzystywane tak często. Gdzie naprawdę potrzebujesz silnego blokuj komentarze znajdują się na czele twoich dokumentów zaplecza lub plików bibliotecznych. Łatwo jest przejść wszystko i napisać solidną dokumentację dla każdego pliku w witrynie - możemy zobaczyć tę praktykę w wielu CMS, takich jak WordPress.

W górnej części strony powinny znajdować się komentarze dotyczące samego pliku. W ten sposób możesz szybko sprawdź, gdzie edytujesz podczas pracy na wielu stronach jednocześnie. Dodatkowo możesz użyć tego obszaru jako baza danych dla najważniejszych funkcji, których potrzebujesz z klasy.

/ ** * @desc ta klasa przechowuje funkcje do interakcji z użytkownikiem * przykłady obejmują user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / klasa abstrakcyjna myWebClass  

Możesz zobaczyć, że użyłem tylko małej próbki do fałszywej myWebClass kod. Dodałem kilka metadanych z moim imieniem i adresem e-mail do kontaktu. Kiedy programiści piszą kod open source, jest to ogólnie dobra praktyka, więc inni mogą skontaktować się z Tobą w celu uzyskania wsparcia. Jest to również solidna metoda podczas pracy w większych zespołach programistycznych.

Metka @wymagany nie widziałem czegoś innego. Nadążam za formatem w kilku moich projektach, tylko na stronach, na których dostosowałem wiele metod. Za każdym razem, gdy dołączasz strony do pliku, muszą pojawić się przed wysłaniem kodu. Tak więc dodanie tych szczegółów do głównego bloku komentarzy klasy jest dobrym sposobem pamiętaj, które pliki są potrzebne.

Komentowanie kodu front-end

Teraz, gdy omówiliśmy 3 ważne szablony komentarzy, spójrzmy na kilka innych przykładów. Jest wielu programistów frontendowych, którzy przenieśli się ze statycznego HTML do jQuery i kodu CSS. Komentarze HTML nie są tak celowe w porównaniu z aplikacjami programującymi, ale kiedy piszesz biblioteki stylów i skrypty stron, rzeczy mogą z czasem stać się chaotyczne.

JavaScript stosuje bardziej tradycyjną metodę komentowania podobną do Java, PHP i C / C++. CSS wykorzystuje tylko komentarze w stylu bloków oznaczone ukośnikiem i gwiazdką. Należy pamiętać, że komentarze będą jawnie wyświetlane dla odwiedzających, ponieważ ani CSS, ani JS nie są analizowane po stronie serwera, ale każda z tych metod działa świetnie, aby pozostawić w kodzie kod informacyjny..

Specyficzne rozbijanie plików CSS może być uciążliwe. Wszyscy znamy pozostawienie komentarza wbudowanego w celu wyjaśnienia poprawki do Internet Explorera lub Safari. Ale wierzę, że komentowanie CSS może być używane na poziomie jQuery i PHP z nich korzystaj. Zajrzyjmy do tworzenia grup stylów, zanim przejdziemy do kilku szczegółowych wskazówek dotyczących komentowania kodu.

Grupy stylów CSS

Dla tych, którzy projektują CSS od lat, jest to prawie druga natura. Powoli zapamiętasz wszystkie właściwości, składnię i zbudujesz własny system dla arkuszy stylów. Dzięki mojej własnej pracy stworzyłem to, co nazywam grupowanie aby sparować podobne bloki CSS w jednym obszarze.

Wracając do edycji CSS, mogę łatwo znaleźć to, czego potrzebuję w ciągu kilku sekund. Sposób, w jaki wybierzesz grupowanie stylów, zależy wyłącznie od ciebie, a to jest piękno tego systemu. Mam kilka predefiniowanych standardów, które przedstawiłem poniżej:

• @ resetowania - usuwanie domyślnych marginesów przeglądarki, wypełnienia, czcionek, kolorów itp.
• @fonts - akapity, nagłówki, cytaty, linki, kod
• @navigation - główne główne linki nawigacyjne
• @layout - opakowanie, pojemnik, paski boczne
• @header & @footer - mogą się różnić w zależności od projektu. Możliwe style obejmują łącza i listy nieuporządkowane, kolumny stopek, nagłówki, podpunkty

Podczas grupowania arkuszy stylów znalazłem system znakowania może bardzo pomóc. Jednak w przeciwieństwie do PHP lub JavaScript używam pojedynczego @Grupa tag, po którym następuje kategoria lub słowa kluczowe. Poniżej zamieściłem 2 przykłady, dzięki którym możesz poczuć, co mam na myśli.

/ ** @grupa stopki * / #footer styles…

/ ** @group footer, małe czcionki, kolumny, linki zewnętrzne ** / 

Możesz też dodać trochę szczegółów w każdym bloku komentarza. Wybieram zachować prostotę i prostotę więc arkusze stylów są łatwe do przejrzenia. Komentowanie dotyczy dokumentacji, tak długo, jak rozumiesz pisanie, dobrze jest iść!

4 wskazówki dotyczące lepszego stylizacji komentarzy

W pierwszej połowie tego artykułu poświęciliśmy różne formaty komentowania kodu. Porozmawiajmy teraz o kilku ogólnych wskazówkach, aby utrzymać kod w czystości, uporządkowany i łatwy do zrozumienia.

1. Zachowaj wszystko do odczytu

Czasami jako deweloperzy zapominamy o tym piszemy komentarze dla ludzi do przeczytania. Wszystkie języki programowania, które rozumiemy, są stworzone dla maszyn, więc konwersja na zwykły tekst może być nudna. Ważne jest, aby pamiętać, że nie jesteśmy tutaj, aby pisać prace naukowe na poziomie uniwersyteckim, ale po prostu zostawiam wskazówki!

funkcja getTheMail () // kod tutaj zbuduje kod e-mail / *, jeśli nasze niestandardowe wywołanie funkcji sendMyMail () zwraca true find sendMyMail () w /libs/mailer.class.php sprawdzamy, czy użytkownik wypełnia wszystkie pola i wiadomość zostanie wysłana! * / if (sendMyMail ()) return true; // zachowaj prawdę i wyświetl sukces na ekranie

Nawet kilka słów jest lepsze niż nic. Kiedy wracasz do edycji i pracy nad projektami w przyszłości, często zaskakuje cię, ile zapomnisz. Ponieważ nie patrzysz codziennie na te same zmienne i nazwy funkcji, często zapominamy o większości kodu. Tak możesz nigdy nie zostawiaj zbyt wielu komentarzy! Ale możesz zostawić zbyt wiele złych komentarzy.

Zgodnie z ogólną zasadą, poświęć trochę czasu, aby się zatrzymać i zastanowić przed napisaniem. Zapytaj siebie co jest najbardziej mylące w odniesieniu do programu i jak najlepiej to wyjaśnić “manekin” język? Rozważ także dlaczego piszesz kod dokładnie tak, jak ty.

Niektóre z najbardziej mylących błędów pojawiają się, gdy zapomina się o funkcjach niestandardowych (lub innych). Pozostaw ślad komentarza prowadzący do kilku innych plików jeśli pomoże to w zapamiętaniu funkcjonalności.

2. Złagodzić trochę przestrzeni!

Nie mogę wystarczająco podkreślić, jak ważne Biała przestrzeń może być. To idzie podwójnie prawda dla programistów PHP i Ruby, którzy pracują na ogromnych stronach internetowych z setkami plików. Będziesz wpatrywał się w ten kod przez cały dzień! Czy nie byłoby wspaniale, gdybyś mógł przejść do ważnych obszarów?

$ dir1 = "/ home /"; // ustaw główny katalog domowy $ myCurrentDir = getCurDirr (); // ustaw aktualny katalog użytkownika $ userVar = $ get_username (); // nazwa użytkownika bieżącego użytkownika

W powyższym przykładzie zauważysz dodatkowe wypełnienie, które umieściłem między komentarzami i kodem w każdym wierszu. Podczas przewijania plików ten styl komentowania będzie wyraźnie się wyróżniają. To ułatwia znajdowanie błędów i poprawianie kodu setki razy gdy zmienne bloki są takie czysty.

Możesz wykonać podobne zadanie w kodzie wewnątrz funkcji, w której jesteś zdezorientowany, jak to działa, ale ta metoda ostatecznie zaśmieci twój kod wbudowanymi komentarzami, a to jest dokładnie odwrotność uporządkowanego! Polecam w tym scenariuszu dodanie dużego komentarza wiersza blokowego wokół obszaru logiki.

$ (document) .ready (function () $ ('. sub'). hide (); // ukryj pod-nawigację na stronie pageload / ** sprawdź zdarzenie click na kotwicy wewnątrz .itm div zapobiegaj domyślnemu linkowi akcja więc strona nie zmienia się po kliknięciu dostęp do elementu nadrzędnego .itm, po którym następuje następna lista .sub, aby przełączyć otwórz / zamknij ** / $ ('. itm a'). live ('click', funkcja (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Jest to niewielki fragment kodu jQuery, który kieruje się do przesuwnej nawigacji w podmenu. Pierwszy komentarz wyjaśnia, dlaczego ukrywamy wszystkie .pod klasy. Powyżej programu obsługi zdarzeń Live Click użyłem komentarza blokowego i nacisnął cały tekst na ten sam punkt. Sprawia to, że rzeczy są ładniejsze niż nieprzypadkowe - szczególnie dla innych czytających twoje komentarze.

3. Komentarz podczas kodowania

Wraz z odpowiednimi odstępami może to być jeden z najlepszych nawyków, do których można się dostać. Nikt nie chce cofać swojego programu po tym, jak działa i dokumentuje każdy kawałek. Większość z nas nawet nie chce wrócić i udokumentować zagmatwanych obszarów! To naprawdę wymaga dużo pracy.

Ale jeśli możesz pisać komentarze podczas kodowania wszystko będzie nadal świeże w twoim umyśle. Zazwyczaj programiści utkną na problemie i przeszukają sieć w celu znalezienia najłatwiejszego rozwiązania. Kiedy trafisz na moment Eureka i rozwiążesz taki problem, na ogół jest moment, w którym rozumiesz swoje poprzednie błędy. To byłoby Najlepszy czas pozostawić otwarte i szczere komentarze na temat twojego kodu.

Dodatkowo pozwoli to ćwiczyć przyzwyczajenie się do komentowania wszystkich plików. Ilość czasu potrzebna do powrotu i obliczenia, jak coś działa, jest znacznie większa po zbudowaniu funkcji. Zarówno twoje przyszłe ja, jak i twoi koledzy z drużyny będą ci dziękować za pozostawienie komentarzy z wyprzedzeniem.

4. Radzenie sobie z błędami Buggy

Nie możemy siedzieć przed komputerem przez wiele godzin, pisząc kod. Przypuszczam, że możemy spróbować, ale w pewnym momencie musimy spać! Prawdopodobnie będziesz musiał rozstać się z kodem na ten dzień, ponieważ niektóre funkcje są nadal zepsute. W tym scenariuszu ważne jest, abyś ty zostaw długie, szczegółowe komentarze na temat tego, gdzie zostawiłeś rzeczy.

Nawet po świeżej nocy możesz być zaskoczony tym, jak trudno jest wrócić do tempa kodowania. Na przykład, jeśli budujesz stronę przesyłania obrazów i musisz pozostawić ją niezakończoną, ty powinien skomentować, gdzie zakończyłeś proces. Czy obrazy są przesyłane i przechowywane w pamięci tymczasowej? A może nawet nie są rozpoznawane w formularzu przesyłania, a może nie są poprawnie wyświetlane na stronie po przesłaniu.

Błędy komentowania są ważne z dwóch głównych powodów. Najpierw możesz łatwo podnieś, gdzie skończyłeś i spróbuj ponownie świeżo na myśl, aby rozwiązać problem (y). Po drugie możesz rozróżniać wersję produkcyjną strony internetowej od strony testowej. Pamiętaj, że należy używać komentarzy wyjaśnij, dlaczego coś robisz, nie do końca to, co robi.

Wniosek

Rozwój aplikacji internetowych i oprogramowania jest praktyką satysfakcjonującą, aczkolwiek trudną. Jeśli jesteś jednym z niewielu programistów, którzy naprawdę rozumieją oprogramowanie do budowania, ważne jest, aby dojrzewać z umiejętnościami kodowania. Pozostawienie komentarzy opisowych jest po prostu dobrą praktyką na dłuższą metę, i prawdopodobnie nigdy tego nie pożałujesz!

Jeśli masz sugestie dotyczące wyraźniejszego komentowania kodu, poinformuj nas o tym w obszarze dyskusji poniżej!