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:16 For those of you who may be new to programming in general, let’s define what a comment is as it pertains to your code. Comments are pieces of text placed among your code to provide annotation.

00:29 Often, people will scribble notes in the pages of their textbooks or the margins of a paper they’re studying.

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.

01:48 Commenting could save you from this type of headache. It comes in handy to explain your present intentions to your future self. Comments in your code will also be appreciated by others.

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:42 Whereas documentation usually has an audience of end users.

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.