Aktualizováno v červenci 2021
Úvod
Klíčovou dovedností při psaní kódu je schopnost používat komentáře. Komentáře jsou řádky, které kompilátoři a interpreti ignorují a které vývojáři používají k zanechání poznámek o funkci kódu. Navíc je lze také použít k deaktivaci částí kódu.
Tento průvodce vám ukáže, jak efektivně používat komentáře v Pythonu.
Předpoklady
- Funkční programovací prostředí Python
- Možnost vytvářet a upravovat soubory Python
Syntaxe komentáře Pythonu
Chcete-li přidat nebo označit řádek jako komentář, začněte křížkou (# ) a mezera :
# This is a sample comment.Použití znaku hash k zahájení řádku říká systému, aby ignoroval vše na tomto řádku. Když aplikace běží, program předstírá, že tyto řádky neexistují. Stále jej však můžete vidět, když soubor upravujete.
Například v Ahoj světe program níže:
# Display the text "Hello, World!" on the screen.
print("Hello, World!")
Systém spustí kód print("Hello, World") na řádku čtyři, zatímco řádek výše vysvětluje, co má kód dělat.
Můžete nastavit libovolný řádek jako komentář a použít jich, kolik chcete. Pokud má váš kód různé bloky, můžete každý z nich vysvětlit pomocí komentáře. Například:
# Define a variable flowers as a list of strings.
flowers = [‘rose’, ‘carnation’, ‘daisy’, ‘marigold’, ‘tulip’, ‘sunflower’]
# Create a for loop to iterate through flowers list, and displays each string item.
for flower in flowers:
print(flower)
Blok komentářů Pythonu
Blokovat komentáře jsou delší komentáře, které se skládají z více řádků za sebou. Vývojář je používá k vysvětlení složitějšího kódu, zejména při práci v týmu.
Chcete-li označit řadu řádků jako komentář, přidejte znak křížku + mezera na začátku každého řádku:
# This is a comment
# that runs on to
# multiple lines.Některé textové nebo kódové editory pro programování (jako Notepad++ nebo Atom) vám umožňují zvýraznit text a poté kliknutím myší označit blok jako komentář. Tyto nástroje vám mohou ušetřit čas při komentování každého řádku.
Python víceřádkový komentář
Obecně se doporučuje používat # na začátku každého řádku jej označit jako komentář. Komentování velké sekce však zabere spoustu času a možná budete potřebovat rychlý způsob, jak okomentovat celou sekci. V takových případech můžete použít víceřádkové komentáře .
Víceřádkové řetězce nefungují jako tradiční komentáře Pythonu, protože neexistuje žádná oficiální víceřádková funkčnost. Místo toho použijte víceřádkové řetězce zabalené do trojitých uvozovek (""" ), abyste dosáhli podobné funkce.
Například:
def addition_test(a, b):
result = a + b
"""
This is a block
of commented lines.
They aren’t parsed and interpreted by the compiler.
"""
return result
Tato metoda vytváří textovou konstantu bez funkce, není pravdivý komentář. Dokud nepřidáte nic, co přistupuje k tomuto řetězci textu, funguje to stejně jako běžný komentář.
Trojité uvozovky mohou být složité, protože za určitých okolností vytváří docstring pokud je to trojitá uvozovka:
- následuje za podpisem funkce,
- dodržuje definici třídy,
- je na začátku modulu.
Pokud umístíte """ na jednom z výše uvedených míst jej Python přečte jako dokumentaci . Docstring vám umožní vložit do projektu text čitelný pro člověka. To se obvykle používá k vytvoření dokumentace, která je součástí aplikace a je přístupná za běhu.
Vložený komentář Pythonu
Komentovat můžete na stejném řádku jako část kódu pomocí vloženého komentáře . Nejlepší čas pro použití této možnosti je při vysvětlování složité operace.
Pomocí vloženého komentáře označte přesné místo, které chcete objasnit. Přidejte standardní znak hash + mezera pro označení vloženého komentáře:
function
set variable
run command
run additional command # Tricky part: The program breaks if this line is removed.Vložené komentáře se používají k přidání kontextu pro lidi, kteří čtou kód. Můžete například vysvětlit účel proměnné nebo zanechat poznámku o typu vytvořené proměnné. Může být také užitečné vysvětlit, proč se konkrétní příkaz používá, jako v příkladu výše.
Odeslání komentáře v Pythonu
Protože komentáře činí text pro analyzátor neviditelný, můžete je použít k deaktivaci příkazů. To vám umožní testovat segmenty kódu s novými přídavky a bez nich.
Například v tomto jednoduchém programu na házení kostkami je část, která je zakomentována. Pokud odstraníte znak hash, povolíte kód k jeho testování.
import random
min = 1
max = 6
roll_again = "yes"
while roll_again == "yes" or roll_again == "y":
print "Rolling the dice..."
print "The values are...."
print random.randint(min, max)
print random.randint(min, max)
# Add two random numbers together for a sum
# while roll_again == “yes” or roll_again == “y”:
# print ”Rolling the dice…”
# print “You rolled a “
# print random.randint(min,max) + random.randint(min, max)
roll_again = raw_input("Roll the dice again?")Proč jsou komentáře v Pythonu důležité
Komentáře vám mohou pomoci:
- Pochopte svůj vlastní kód, když se k němu vrátíte po delší době.
- Zrychlete návrat na rychlost.
- Problémy s laděním.
- Pochopte určité volby kódu při práci v týmu.
- Předjděte potenciálním problémům zdůrazněním, proč je konkrétní část kódu důležitá.
Osvědčené postupy pro komentáře ke kódu Python
- Komentujte se stejným odsazením jako kód, na který odkazujete. Snáze tak uvidíte, na co odkazujete.
- Při aktualizaci kódu aktualizujte své komentáře. Nesprávné komentáře jsou horší než žádné komentáře.
- Používejte celé věty. Vhodná slova pište velkými písmeny, pokud nemáte na mysli identifikátor (např. proměnnou). Nikdy neměňte malá a velká písmena identifikátoru.
- Blokové komentáře by měly být psány celými větami s tečkami. Zaměřte se na 80 slov na řádek nebo méně.
- Pokud máte v komentáři více vět, použijte mezi větami dvojitou mezeru.
- Psát komentáře v angličtině.
- V případě blokového komentáře s více odstavci přidejte mezi odstavce prázdný řádek s jedním tagem komentáře před prázdným řádkem.
- U vložených komentářů ponechte mezi kódem a komentářem alespoň dvě mezery. Používejte vložené komentáře střídmě a nepoužívejte je k vyjádření toho, co je zřejmé.
VYVARUJTE SE:
- Nekomentujte kód, který je samozřejmý. Držte se zásady psaní SUCHÉ (D ne R opakujte Y my sami) a vyvarujte se MOKRÉ (W obřad E úplně všechno T wice) kód a komentáře.
- Nepoužívejte komentáře k vysvětlení chaotického kódu – komentáře by měly kód podporovat, nikoli jej ospravedlňovat.