Comments in Python: How to Document Your Code

comments-in-pythonComments are a part of all coding projects, but coders usually hate the process of commenting code. Comments help you remember the purpose of a function. They also help other programmers when they are responsible for maintaining your code. There are good and bad commenting practices in any language including Python. However, Python has its own commenting syntax that you should know. Incorrect commenting syntax leads to code that throws errors and won’t compile. Knowing how to comment code in Python is more than just knowing syntax. You must know how and when to comment your code.

Learn Python from the very beginning

Python Comment Syntax

There are two types of comments in Python. The first is an inline comment system. Inline comments are the comments that follow a line of code. The following is an example of an inline comment in Python:

x = x + 1                 # add 1 to x and store it in x

The above is a simple comment, and you actually wouldn’t comment like the above, because the Python statement is too obvious even for new Python developers. However, the above statement is a good example of an inline comment. The “x = x + 1” will execute properly and add 1 to the x variable. Any characters after the # character are ignored. This means that you can even have code after the hash mark and the compiler still won’t attempt to run the statement.

Take the ultimate Python class and learn everything you need at Udemy.com

The next type of comment system is comment blocks. There are times when you need to leave several sentences to explain the way the code executes. Inline comments won’t work, because those sentences will take up several lines in your editor. The answer is to use a comment block. The below example is a comment block in Python:

“”” This is a comment block.

It takes up multiple lines and can be used

in any place in your code. “””

Notice the triple quote characters. These characters are used to denote a comment block. You can have one or hundreds of sentences within the quote characters, however you wouldn’t normally have several hundreds of comments.  Just like the inline comments, the compiler completely ignores these statements, so you can even have code in a comment block and it will be ignored. You can’t cause any errors as long as code or text is located within the quotes characters.

How to Properly Comment Your Code

Commenting syntax is easy to learn and remember, but the difficult part is understanding how to properly comment your code. Comments are a part of code documentation, so it’s important to create comments while you code. However, it’s easy to ignore or forget to comment the code. It’s also common for developers to incorrectly comment code.

The first rule when commenting is to know your audience. Your audience is always other coders. This means that you don’t need to explain every line of code especially the easily understood lines. For instance, when you declare a variable, you don’t need to explain that you’re declaring a variable. A coder already knows what a variable declaration statement is for, but you can describe why you’re declaring the variable. For instance, you might declare a temp variable that you will use several lines down the code editor. The coder might not understand why you declare an extra variable at the beginning of the code. You can leave a note next to the temporary variable to explain why the variable is declared and what it’s used for later in the code.

Take your Python skills to the next level at Udemy.com

The next rule is to comment your code for loop structures. Loops can be more difficult to understand and the logic behind you have them. You use the comment blocks to explain the loop and its purpose as it relates to the rest of your code.

Another big comment requirement is functions and class methods. Functions and class methods are usually large blocks of code that perform a critical function in your software. It’s also likely that a coder will need to use your class methods and function with his own code. It helps other coders when you explain exactly what the function does and how it can be worked with other parts of the software. Most coding editors allow a user to view where functions are called, so they know if they can edit the function. Typically, coders create overloaded methods instead of rewriting a method, because changing the current one can create bugs in the code.

While you don’t need to overload your code files with comments, it can greatly help other coders understand your code. You can also look into UML encoded comments. UML is a commenting standard that you can add to your code files. Some programs will go through UML encoded comments, parse them out and then create documentation for you. If you comment your code as you work, you also save time, because you don’t need to go back to your code after it’s complete and re-add comments.

New to computer programming? Learn how to code at Udemy.com

While most coders hate documentation and commenting, you can save yourself hours if you keep your comments organized. Make sure you comment difficult functions and methods, and even go back later and proof them. You want to make sure you understand the logic behind the functions and methods, and proofing can help ensure that they make sense to coders who must maintain your software in the future.