Python Comments

Oct 7, 2023

DataSciencePursuit

Comments are notes within the code cell.

They are completely ignored by the computer as they are meant for people.

Writing a comment

Comments start with a # (number, pound, or hash symbol). This is similar to the headers in markdown, but you do not need a space, except for readability.

You can add comments on their own line or at the end of any line of code.

Notice that we do not get any output from either comment, as the computer ignores these. Also, notice that the comments are green to help you spot them more easily.

If you leave out the # sign, you will get a syntax error.

A free sentence like this is not part of the Python programming language.

Uses

Comments are important for:

  1. Documenting code (to help people understand the code)
  2. Debugging (checking and correcting errors)

Documenting code

Comments can help yourself, your future self, and other people understand code.

For documentation purposes, comments can be used to:

  1. Explain why something was done (the logic behind the steps): The most important thing is to write why you are doing something. Your logic, the way that you solve problems can be different from the next person, or even your future self. Reading the code can tell you what it's doing, but it cannot tell you why it's doing something or what the programmer's original intentions were. Writing the logic can help your future self and other people understand the code or identify possible semantic errors.
  2. Explain what the code does (very useful for beginners): You can also write what the code is doing which I think can be very helpful for beginners and I really encourage that. Since we are all beginners here, use comments in whatever way that helps you. We will do the same with our comments here in this course to help you learn. However, as you become more of an intermediate, writing what the code is doing becomes less necessary as reading it will tell you exactly that.

Note: if you add the comment at the beginning then you have turned that line into a comment, it will not be run. This is useful for debugging

Debugging

Comments can also be used to prevent code from being executed. You can comment out the line you do not want to run, by putting a # in front of the line of code.

In the example below we comment out the part that updates the age to 45, and you will see that the age remains as 32.

This can help with error checking, especially when you have a cell with a lot of code. You can comment out parts of the code you think may be producing an error, to see if those parts are truly the problem.

Multi-line comments

If you write a super long comment python will make the cell scrollable so you can read all of it, but this is the best experience.

Instead, you can break up your comment into multiple lines that fit on the screen.

Keyboard shortcuts

To comment out or uncomment code:

  • highlight the lines of code (for one line, you can also just click anywhere on the line)
  • press Ctrl + / on Windows or Cmd + / on Mac

Next steps

Now we have learned 2 forms of communication in programming:

  • code: communication between people and computers
  • comments and markdown: communication between people

Later we will learn about strings, which can also be used as a third unofficial way to add notes to code. They are used a lot to document functions. And Python functions will be our next topic!