Komentarze w kodzie (Visual Basic)

Czytając przykłady kodu, często napotykasz symbol komentarza (').Ten symbol informuje kompilator Visual Basic o tym, aby zignorować tekst następujący po znaku, czyli komentarz.Komentarze to krótkie notatki wyjaśniające, dodane do kodu, aby ułatwić życie innym osobom, które go czytają.

Dobrą praktyką programowania jest rozpoczynanie wszystkich procedur od krótkiego komentarza, który opisuje charakterystykę funkcjonalną procedury (co dana procedura robi).Korzysta z tego i sam programista, i wszyscy inni, którzy czytają kod.Szczegóły dotyczące implementacji (jak procedura coś robi) należy oddzielić od komentarzy opisujących charakterystyki funkcjonalne.Gdy w opisie dołączasz szczegóły dotyczące implementacji, pamiętaj, aby je zaktualizować, gdy aktualizujesz funkcję.

Komentarze mogą następować po instrukcji w tym samym wierszu lub zajmować cały wiersz.Poniższy kod ilustruje obie wersje.

' This is a comment beginning at the left edge of the screen.
text1.Text = "Hi!"   ' This is an inline comment.

Jeśli komentarz wymaga więcej niż jednego wiersza, należy użyć symbolu komentarza w każdym wierszu, jak pokazuje poniższy przykład.

' This comment is too long to fit on a single line, so we break  
' it into two lines. Some comments might need three or more lines.

Wytyczne komentowania

Poniższa tabela zawiera ogólne wytyczne na temat tego, jakie rodzaje komentarzy mogą poprzedzać sekcję kodu.Są to propozycje; Visual Basic nie wymusza zasad dodawania komentarzy.Pisz to, co się najlepiej sprawdza, zarówno dla ciebie, jak i dla każdego, kto czyta twój kod.

Typ komentarza	Opis komentarza
Przeznaczenie	Opisuje, co procedura robi (a nie jak to robi)
Założenia	Wymienia każdą zewnętrzną zmienną, element sterujący, otwarty plik lub inny element, do którego procedura uzyskuje dostęp
Efekty	Wymienia każdą zewnętrzną zmienną, element sterowania lub plik i efekt, jaki wywołuje (tylko jeśli nie jest on oczywisty)
Dane wejściowe	Określa cel argumentu
Zwraca	Wyjaśnia wartości zwrócone przez procedurę

Należy pamiętać o następujących kwestiach:

• Każda ważna deklaracja zmiennej powinna być poprzedzona komentarzem opisującym użycie deklarowanej zmiennej.

• Zmienne, elementy sterujące i procedury powinno się nazywać na tyle jasno, żeby komentowanie było konieczne tylko w przypadku szczegółów złożonych implementacji.

• Komentarze nie mogą występować w tym samym wierszu, jeśli jest on kontynuowany w następnym.

Możesz dodawać lub usuwać symbole komentarza dla bloku kodu, zaznaczając jeden lub więcej wierszy kodu i wybierając przyciski Zakomentuj () i Odkomentuj () dostępne na pasku narzędzi Edycja.

[!UWAGA]

Możesz również dodawać komentarze do kodu, poprzedzając tekst słowem kluczowym REM.Jednak symbol ' i przyciski Zakomentuj/Odkomentuj są łatwiejsze w użyciu i wymagają mniej miejsca i pamięci.

Zobacz też

Zadania

Porady: tworzenie dokumentacji XML w Visual Basic

Informacje

Zalecane tagi XML dla komentarzy dokumentacji (Visual Basic)

REM — Instrukcja (Visual Basic)

Inne zasoby

Dokumentowanie kodu przy użyciu komentarzy XML

Struktura programu i konwencje związane z kodami (Visual Basic)