Wie man Kommentare in Python 3 schreibt

Einführung

Kommentare sind Zeilen, die in Computerprogrammen existieren und von Compilern und Interpretern ignoriert werden. Die Verwendung von Kommentaren in Programmen kann den Code für Menschen lesbarer machen, da sie Informationen oder Erklärungen darüber liefern, was jeder Teil eines Programms tut.

Je nach Zweck Ihres Programms können Kommentare als Notizen für Sie selbst oder als Erinnerungen dienen, oder sie können mit dem Anliegen verfasst werden, dass andere Programmierer verstehen, was Ihr Code tut.

Im Allgemeinen ist es eine gute Idee, während des Schreibens oder Aktualisierens eines Programms Kommentare zu verfassen, da es leicht ist, den eigenen Denkprozess später zu vergessen, und später geschriebene Kommentare langfristig weniger nützlich sein können.

Voraussetzungen

Sie sollten Python 3 installiert und eine Programmierumgebung auf Ihrem Computer oder Server eingerichtet haben. Wenn Sie keine Programmierumgebung eingerichtet haben, können Sie auf die Installations- und Einrichtungsanleitungen für eine lokale Programmierumgebung oder für eine Programmierumgebung auf Ihrem Server verweisen, die für Ihr Betriebssystem (Ubuntu, CentOS, Debian usw.) geeignet ist.

Kommentar-Syntax

Kommentare in Python beginnen mit einem Hash-Zeichen (#) und einem Leerzeichen und ziehen sich bis zum Ende der Zeile.

Im Allgemeinen werden Kommentare ungefähr so aussehen:

This is a comment

Da Kommentare nicht ausgeführt werden, werden Sie beim Ausführen eines Programms keine Hinweise auf den Kommentar sehen. Kommentare sind im Quellcode für Menschen zum Lesen, nicht für Computer zum Ausführen.

In einem “Hello, World!” Programm könnte ein Kommentar so aussehen:

Print “Hello, World!” to console
print("Hello, World!")

In einer for-Schleife, die über eine Liste iteriert, können Kommentare so aussehen:

Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

Kommentare sollten auf derselben Einrückungsebene wie der Code, den sie kommentieren, vorgenommen werden. Das heißt, eine Funktionsdefinition ohne Einrückung hätte einen Kommentar ohne Einrückung, und jede folgende Einrückungsebene hätte Kommentare, die mit dem Code, den sie kommentieren, ausgerichtet sind.

Zum Beispiel, hier ist, wie die again() Funktion aus dem Tutorial "Wie man ein einfaches Taschenrechnerprogramm in Python 3 macht" kommentiert ist, mit Kommentaren, die jeder Einrückungsebene des Codes folgen:

...
Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

Kommentare werden erstellt, um Programmierern zu helfen, egal ob es sich um den ursprünglichen Programmierer oder jemand anderen handelt, der an dem Projekt arbeitet oder mitarbeitet. Wenn Kommentare nicht richtig gepflegt und zusammen mit dem Code aktualisiert werden können, ist es besser, keinen Kommentar einzufügen, anstatt einen Kommentar zu schreiben, der dem Code widerspricht oder widersprechen wird.

Beim Kommentieren von Code sollten Sie versuchen, die Warum hinter dem Code zu beantworten, anstatt das Was oder Wie. Es sei denn, der Code ist besonders knifflig; in der Regel kann man durch einen Blick auf den Code erkennen, was der Code tut oder wie er es tut.

Blockkommentare

Blockkommentare können verwendet werden, um komplizierteren Code oder Code zu erklären, mit dem Sie nicht erwarten, dass der Leser vertraut ist. Diese längeren Kommentare beziehen sich auf einen Teil oder den gesamten folgenden Code und sind ebenfalls auf derselben Ebene wie der Code eingerückt.

In Blockkommentaren beginnt jede Zeile mit dem Rautezeichen und einem einzelnen Leerzeichen. Wenn Sie mehr als einen Absatz verwenden müssen, sollten diese durch eine Zeile getrennt werden, die ein einzelnes Rautezeichen enthält.

Hier ist ein Beispiel für einen Blockkommentar, der beschreibt, was in der main()-Funktion passiert, die im Folgenden definiert ist:

The main function will parse arguments via the parser variable.  These
arguments will be defined by the user on the console.  This will pass
the word argument the user wants to parse along with the filename the
user wants to use, and also provide help text if the user does not
correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

Blockkommentare werden typischerweise verwendet, wenn Operationen weniger verständlich sind und daher eine umfassende Erklärung erfordern. Du solltest versuchen, es zu vermeiden, den Code übermäßig zu kommentieren, und solltest dazu neigen, anderen Programmierern zu vertrauen, dass sie Python verstehen, es sei denn, du schreibst für ein bestimmtes Publikum.

Inline-Kommentare

Inline-Kommentare treten in derselben Zeile wie eine Anweisung auf, direkt nach dem Code selbst. Wie andere Kommentare beginnen sie mit einem Hash-Zeichen und einem Leerzeichen.

Im Allgemeinen sehen Inline-Kommentare so aus:

[code]  # Inline comment about the code

Inline-Kommentare sollten sparsam verwendet werden, können jedoch effektiv sein, um schwierige oder komplexe Teile des Codes zu erklären. Sie können auch nützlich sein, wenn Sie denken, dass Sie sich in Zukunft möglicherweise nicht an eine Zeile des Codes erinnern werden, den Sie gerade schreiben, oder wenn Sie mit jemandem zusammenarbeiten, von dem Sie wissen, dass er möglicherweise nicht mit allen Aspekten des Codes vertraut ist.

Zum Beispiel, wenn Sie in Ihren Python-Programmen nicht viel Mathematik verwenden, wissen Sie oder Ihre Mitarbeiter möglicherweise nicht, dass Folgendes eine komplexe Zahl erstellt, daher möchten Sie möglicherweise einen Inline-Kommentar dazu einfügen:

z = 2.5 + 3j  # Create a complex number

Inline-Kommentare können auch verwendet werden, um den Grund für das Durchführen einer Handlung zu erklären oder um zusätzliche Informationen bereitzustellen, wie zum Beispiel:

x = 8  # Initialize x with an arbitrary number

Kommentare, die inline erstellt werden, sollten nur verwendet werden, wenn sie notwendig sind und wenn sie hilfreiche Hinweise für die Person, die das Programm liest, bieten können.

Code zum Testen auskommentieren

Neben der Verwendung von Kommentaren zur Dokumentation von Code kann das Raute-Zeichen auch verwendet werden, um Code auszukommentieren, den Sie nicht ausführen möchten, während Sie ein Programm testen oder debuggen, das Sie gerade erstellen. Das bedeutet, wenn Sie nach der Implementierung neuer Codezeilen auf Fehler stoßen, möchten Sie möglicherweise einige davon auskommentieren, um herauszufinden, ob Sie das genaue Problem diagnostizieren können.

Die Verwendung des Hash-Zeichens ermöglicht es Ihnen auch, Alternativen auszuprobieren, während Sie herausfinden, wie Sie Ihren Code einrichten. Zum Beispiel könnten Sie entscheiden, ob Sie in einem Python-Spiel eine while-Schleife oder eine for-Schleife verwenden möchten, und können eine von beiden auskommentieren, während Sie testen und herausfinden, welche am besten ist:

import random

number = random.randint(1, 25)

number_of_guesses = 0

for i in range(5):
while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

Das Kommentieren von Code mit dem Hash-Zeichen ermöglicht es Ihnen, verschiedene Programmiermethoden auszuprobieren und hilft Ihnen zudem, die Quelle eines Fehlers zu finden, indem Sie systematisch Teile eines Programms kommentieren und ausführen.

Schlussfolgerung

Kommentare in Ihren Python-Programmen zu verwenden, hilft, Ihre Programme für Menschen, einschließlich Ihres zukünftigen Ichs, lesbarer zu machen. Angemessene Kommentare, die relevant und nützlich sind, können es anderen erleichtern, mit Ihnen an Programmierprojekten zusammenzuarbeiten und den Wert Ihres Codes klarer zu machen.

Von hier aus möchten Sie möglicherweise über die Docstrings von Python in PEP 257 lesen, um Ihnen weitere Ressourcen zur richtigen Dokumentation Ihrer Python-Projekte zu bieten.