Programming with Python
Making your code clear to everybody: comments and pseudocode in Python

Photo by Clarisse Meyer on Unsplash

Making your code clear to everybody: comments and pseudocode in Python

Paolo Re's photo
Paolo Re
·

3 min read

Comments

In programming, comments are text annotations that are typically added to source code to explain it or make it more understandable. These comments are not executed by the system when the code is run. Rather, they are notes for other programmers who are reading the code.

Comments can be used to provide context, explain what the code is doing, or describe how it is doing it. They can also be used to temporarily disable lines of code for testing or debugging purposes.

It is generally considered good practice to add comments to your code as it makes it easier for other developers to understand the codebase. However, it is also important to ensure that the comments are clear and accurate, as unclear or misleading comments can make the code more difficult to understand.

What are the advantages of writing comments?

Comments are a significant feature in Python, the main advantages of comments include:

  • Increasing readability

  • Including resources

  • Disabling parts of the program for debugging purposes

  • Describing and explaining the logical passages utilized

  • Understanding the code after a large amount of time

In Python, to create a comment, you have to type the # character. Anything that follows the # is considered a comment and will be ignored by the interpreter.

# Ask the user for their name
user_name = input("Enter your username: ")
print("Welcome back,")
print(user_name)

There will be times when the comment you need to write is not fully contained in a single line. For this purpose, you can create multi-line comments beginning and ending your annotation with """.

How to write good comments in Python?

To write good comments in Python, many tips help programmers accomplish a well-written comment:

  • Avoid writing obvious or generic comments

  • Keep comments short and to the point

  • Be consistent in your comment style

  • Use comments to clarify your intent

  • Make sure to update comments when changing code

Pseudocode

Pseudocode is a methodology that allows programmers to represent the implementation of an algorithm. The purpose of pseudocode is to help programmers plan out the logic of a program before they start writing actual code. Pseudocode allows programmers to explore different approaches to solving a problem and to visualize how their code will work before they start writing it.

What are the advantages of writing pseudocode?

Writing pseudocode is an excellent practice for a programmer, here are some advantages of implementing it in your program:

  • Improves the implementation of any feature in a program

  • Represents the logic of a program in a simple way

  • Helps document the structure and the flow of the code

  • Improves communication with other programmers

Below, you can see an example of pseudocode and the way it is used:

# Write a program that asks the user for their name, stores it in a variable and then prints it with a welcome message
user_name = input("Enter your username: ")
print("Welcome, ")
print(user_name)

How to write good pseudocode in Python?

As for the comments, some practices help programmers write good pseudocode:

  • Focus on the logic of the program rather than the syntax

  • Use plain English

  • Break your code into smaller portions

  • Be clear and concise

  • Use descriptive variable names

Conclusion

Comments and pseudocode are tools that help programmers write better code. They are ignored by the interpreter and their main purpose is to facilitate the comprehension of the program. Overall, being able to write good comments and pseudocode will make you a more complete and expert programmer.

Pythonpython beginner