In this lesson, you’ll learn what comments are and also one good use of commenting Python code.
The Importance of Writing Good Code Comments
00:02 Welcome to our video guide for writing comments in Python. In this series of videos, we’ll tell you why commenting your code is important, how to write comments, along with the best and worst commenting practices.
00:36 These notes are similar to how comments would be used in a computer program. The programming language you’re using typically has a symbol or symbols to designate text as a comment section so the compiler or interpreter ignores it.
00:51 You can place any notes you want into the comments and there will be zero effect on your program’s operation. Comments can serve a variety of purposes. Uses for code comments include—among other things—planning and reviewing, describing your code, implementing a tagging system, or even using comment syntax to disable portions of your code for debugging.
01:15 Commenting your code is very important, and there are many reasons why, as you’ll see. Let’s start with a very simple premise. Commenting is a gift you give yourself and others. Let me explain what I mean.
01:29 You may have had the experience of writing a program a while back and returning to it at a later time. If enough time has passed, it can be daunting to pick up where you left off. Even worse, you could find your own code confusing, and you may waste time recreating code and encountering the same old problems.
02:01 Your code may be on a shared public repository, or you may be working with a team of people who have to build upon your work. Instead of them trying to infer meaning from your code, you can explicitly state your meaning through comments. Before we get to work creating comments, let’s clarify some terms.
02:22 Code commenting is sometimes confused with the word documentation. While many use these terms interchangeably, there is a slight difference. The main audience for code comments is developers. You’re explaining to yourself or others the intent behind your code.
02:48 Code comments tend to be more concise and descriptive, while documentation can be more verbose but instructive. Now that you understand why we comment, let’s see how we comment—in the next video.
Become a Member to join the conversation.