Hello, and welcome! My name is Ben Lambert, and I’ll be your instructor for this course. This course is part of a series of content designed to help you learn to program with the Python programming language. 

Should you wish to ask me a specific question, you can do that with the contact details on screen. You can also reach support by using the email address: support@cloudacademy.com. And one of our cloud experts will reply.

It might be easy to assume that the sole purpose of the code we create is to control the Python runtime. However, that’s only part of the picture. Python’s language syntax is designed to make the intent of code easier to understand for humans.

Afterall, computer’s understand one and zeros. They don’t need some fancy language. So, Python’s language is intended to make the purpose of code clear to Python developers. And despite our best efforts, sometimes the intent of our code remains unclear. 

For cases like this Python provides a mechanism which enables us to include some notes in our code. These notes are referred to as comments and they’ll be our focus for this lesson. There are two types of comments; single line and multi-line. Single line comments begin the number-sign. Also called a pound-sign or hash-sign. When the interpreter encounters this symbol it assumes that the rest of the line following the symbol should be ignored. 

This style of comment is typically used to describe some code near the comment. Perhaps just before or just after some other code. Comments are used to include some notes to future developers to help make the intent of some bit of code clearer. 

For example: you could include a comment which informs other developers why you’ve included a specific bit of code. Imagine that you have a list of names and you don’t know if these names are using proper casing. So you choose to normalize them by converting them all to title case. 

Adding a comment here let’s future developers know the reason this code exists is to make the names more consistent. It’s worth noting that when I talk about future developers reading your code, I’m including your future self. When you start working on code that you haven’t worked with in a while, it often takes a while and some debugging to refamiliarize yourself with the intent of all the code.

A good comment can save time and effort further down the road. This single line syntax can be used on its own line, or it could be used to add a comment at the end of a line of code. 

For example: imagine that we’re going to send out some invites and we need to know how many. So we use the built-in len function to count the people. Using the single-line comment we can include a note at the end of the line which describes the purpose of this code. 

It doesn’t matter where our comment is located. Just know that any text to the right of a single line comment is ignored by the interpreter. Let’s talk about multi-line comments. Multi-line comments are created using multi-line strings. Python has two versions of the multi-line string. The first uses a pair of three single quotes and the other uses a pair of three double quotes. 

So, if we use multi-line strings as multi-line comments, you might be wondering the difference between the two. When using a multi-line string as a string we actually have the interpreter do something with the string. For example, formatting it with some placeholder values. This means we bind it to a name, pass it to a function, or something else like that. 

When using a multi-line string as a comment we simply do nothing with the string. We don’t bind it to a name, or use it in any way. It just exists to serve as a form of documentation to other developers.

This style of comment can be just about anywhere in code to define a multi-line comment. However, when this style of comment is used in certain contexts it has meaning to the interpreter. 

This style of comment is part of the interpreter’s docstring systems. A docstring is a multi-line comment which is used at the start of a script, module, class, or callable. When the interpreter encounters this style of comment in these locations it treats them as documentation for the given context. 

Here’s an example of a module’s docstring which comes from Python’s built-in color system module. It provides some basic details about the purpose of the module and the functions provided. Here’s another example of this style being used to document a class definition.

When the interpreter encounters this style of comment in specific contexts it automatically assumes that the comment is documentation. Docstring comments are more than just comments. They’re often extracted to become online documentation for developers. 

Docstring comments are intended to help developers understand the code so that they can use it. Docstrings tend to describe the purpose of the piece of code as well as details about input and output. Okay, let’s take a moment to talk about writing useful comments. 

Comments should convey something to future developers that will help them better understand the purpose of the code. Let’s look at an example of comments which don’t add any real value. This first comment indicates that we’re going to create a list of people. Then the next line creates a name and binds it to a list of people.

Through the name binding alone it’s reasonably clear that this line creates a list of people. This comment describes what’s happening and doesn’t consider why it’s happening. A Python developer knows how to create a list. So this comment doesn’t really add any value. 

Let’s look at the next comment. It says make it titlecase. Okay, we can infer from the code that this line is going to produce a list of title case strings. What’s not clear is why we care if they’re title-cased or otherwise. 

And finally, we have the comment: count people. Again we can infer what is happening by the code. What’s not always clear is the reason why we’ve written this code and not something else. Let’s compare this code with something with slightly more expressive comments. Notice in this case start with a comment which indicates that this list includes names of unknown letter casing.

Then it explains that it’s going to normalize the strings for consistency. And finally, it attempts to explain the purpose for the count_of_people. Regardless of the style of comment, the purpose is the same. Comments help future developers - including your future self - to better understand the purpose of the code. 

Comments also serve another use case. Often as you’re developing you’ll have some bit of code that you’ll want the interpreter to ignore. By turning the code into a comment, it will prevent the code from running. This is referred to as “commenting out code.” 

That’s a term you’ll likely hear or see used by other developers. For example: try commenting out line three and your code will work. Actually, this is done commonly enough that most code editors include a keyboard shortcut to comment and uncomment all the selected lines at once. 

Okay, this seems like a natural stopping point. Here are your key takeaways for this lesson:

• To create a single-line comment we can use the number-sign followed by the comment. 

• These can be used on their own line or at the end of some code.

• To create a multi-line comment we can use a multi-line string.

• And when we use this style of comment in certain contexts, the interpreter automatically assumes the comment is a docstring.

• Docstrings are just multi-line comments used to document certain pieces of code such as:

• Modules

• Classes

• Callables

Alright, that's all for this lesson. Thanks so much for watching. And I’ll see you in another lesson!