Like many other high-level programming languages, Python allows you to leave comments in the source code of a program. Comments are of two kinds: single-line and multiline, depending on the number of lines they take up. You can use docstring constructs to create comments on various modules, classes, functions, and methods.
What are comments and why are they needed?
Comments are usually called text explanations, which improve the understanding of the code and are located directly in the program. Because of the special syntax, they stand out from the instructions intended to be executed by the computer. This allows the compiler and interpreter to ignore such text boxes when processing the source code of a program.
So, comments are special text strings that do not affect the execution of the program in any way. You can write anything you want in them, because the compiler and the interpreter will not pay attention to them. Proper use of comments can significantly improve the understanding of the program text by others when working on a common project. In addition, the implementation of such explanations helps their author to quickly understand the previously written code. Such a need often arises when it is necessary to improve or modify the program.
Every separate programming language has its own syntax of single-line comments. Often this is a double slash (//), which tells the computer that the next line is a comment. In Python, the usual slash character (#) performs this function. This code shows how to make two one-line comments inside the program.
# this is a comment # print("Hello World!")
If you run the program with this code, nothing happens because, as we said before, the comments are completely ignored by the computer. You can write explanations not only in English but in Russian too. For Russian comments in Python, you need to enable the UTF-8 encoding (Unicode Transformation Format, 8-bit). Otherwise, the compiler will give an error, not being able to recognize Cyrillic characters correctly.
# coding: utf-8 # is a comment
A comment can be placed in any part of a program, closing off from the compiler not only the whole line, but also the part that follows the lattice character. A comment that follows a certain command should, as a rule, convey its meaning as succinctly as possible. In the following example, the comments show the start and end points of the program, and also convey the purpose of print().
# coding: utf-8 # program start print("Hello World!") # prints the greeting # program end
When creating comments it is important to remember that the grid symbol is not used for its intended purpose if it is enclosed in a string literal. In the code snippet below this operator is part of a string called string. When working in the IDE (Integrated Development Environment), you will see that comments are automatically italicized and highlighted to make them easier to recognize.
string = "# this is not a comment."
After you enter a hash character, all further text will be considered a comment, no matter what keywords or operators are used behind it.
string = "text" ####### this is a comment #######
In the above code snippet, the string initialization is followed by a one-line comment. Thus, the number of lattice characters can be arbitrary.
Most of the high-level programming languages support multi-line comments that help to describe the details of the implementation of complex code blocks in more detail. The common syntax for this construction is a slash with an asterisk at the beginning of the highlighted block (/*) and the same characters in reverse order at the end of the comment (*/). However, Python does not support such a feature, instead suggesting using a bunch of single-line comments.
# coding: utf-8 the # program Hello World # creates and displays a string # program starts greeting = "Hello World!" # creates string print(greeting) # prints the string on the screen # end of program
The program above has a set of single-line comments that Python uses to generate a block of commented comments about the code. Those who work with a simple code editor or notepad will find this approach very inconvenient because you cannot select and comment out multiple lines of code simultaneously, thus preventing them from running. Instead, you have to comment everything separately. However, modern IDEs and code editors such as PyCharm or NetBeans can not only display the language syntax, but also support multiple hotkeys for faster writing programs. You can use them to instantly comment out a huge block of code, as well as quickly get rid of the grid characters at the beginning of each line. This significantly speeds up the work of the programmer and improves the convenience of testing. For example, to comment out several lines of Python code in PyCharm, you should select them and press <Ctrl>+</> key combination.
To create documentation for various modules, classes, functions and methods in Python, a tool called docstring is widely used. According to PEP 8 (Python Enhancement Proposal), which is a set of generally accepted coding guidelines, Python docstring should be used as an explanatory construct for all blocks you create. Such annotations should be placed immediately after defining a class, method, function or module, enclosing the text in triple quotes.
# coding: utf-8 # hello world program def greeting(): """Hello function. Creates and displays a string on the screen. """ greeting = "Hello World!" # create a string print(greeting) # prints the string greeting() # call the greeting() function print(greeting.__doc__) # print docstring
This example shows how the greeting() function creates and prints out a string. Here we have docstring, which tells the programmer the basic information about the method being called. Unlike usual comments, docstring is usually processed by the compiler and placed in the resulting byte-code. At runtime, the previously written information can be displayed using the __doc__ method. The PEP 8 specification defines basic guidelines for using docstring. According to generally accepted norms in Python function comments, the first line of documentation should be a concise summary of the purpose of the object, starting with a capital letter and ending with a period. The second line must be blank, while subsequent paragraphs may contain a more detailed description of the internal features of the object, its characteristics, calling features, and third-party effects.
Using docstring as a comment
Although there is no direct ability to create multi-line comments in Python 3 code, the Python language allows you to use the docstring tool to replace them. You can do this with triple quotes by simply putting the text you want in them. This creates a multi-line literal that does not belong to any object, and therefore plays no role during compiler processing of program code. The following example shows the use of docstring as a multi-line annotation in code.
# coding: utf-8 """ the Hello World program creates and displays the string """ # program starts greeting = "Hello World!" # creates a string print(greeting) # prints the string # end of program
While this approach is simple, it is not recommended because the main purpose of docstring is to document objects.
It is for this reason that it is always better to use grating characters when commenting out large amounts of code using IDE hotkeys.
Comments in the Python programming language are used to create your own explanations of the source code of a program. This helps improve other people’s understanding of it as they work on large projects as a team. The language only provides single-line comments, but you can use text blocks to get the equivalent of multi-line comments. To create documentation for individual functions, methods, classes, and modules, docstring constructs are used. Generally accepted rules for documenting source code are described in detail in the PEP 8 guidelines.