Skip to content
← Back to Community
Commenting Your Code
Profile icon
LeonDoesCode

Mmm

Yep, none of us like to do it. Rather, none of us would like to admit that we know we won't be looking at the project any time soon. So we don't comment the code, telling others that "I can just read through it when I look at it next". And you know that don't work.

So let's stop kidding around, and look at simple ways we can comment the code. These wont require you to write heaps of comments, but can help a lot when comming back to your code. This is also a very opinionated subject, so do as you please, and leave your suggestions below for how you do it.

Where Does This Start?

So adding a comment for the section of code you are writing may seem useless. That may be because the variable or classes names suggest what it is already. But, having an opening and closing comment for each section can shorten searching times a lot. Not only because you can visually see where it is, but because you can easier use the find toold to jump to that section.

It's as simple as doing:

bot.py

""" Bot """ def genId(): # Code here def genColor(): # Code here class Bot: def __init__(self): # Code here

You may even add an ending one to make it even easier to notice when reading.

What Does This Look Like?

Especially in collaborative projects, knowing what includes what can be very important. If you are designing a frontend, and you receive some data from the backend, you want to know what is included in that data. Having a little comment to show what is can make everything much more smooth.

server.js

socket.on("message", data => { /* data { id: 123, text: "...", color: "#..." } */ console.log(`${data.color}:${data.id}:${data.text}`); });

client.js

/* data { id, text, color } */ let data = {id:123, text:"...", color: "#...}; socket.emit("message", data);

The nice thing with most editors now days, is that they let you collapse comments. So even if one of these comments was large, you can easily move them out of the way.

Who Made This?

This is a common one which people include, however, some don't. All this is, is a little comment at the top of the main file or all of them. It shows you who made it, the title of it, a description, and may be a few other details. Simple, but useful.

login.py

""" Login: The easy way to create logins By: Leon Davis Created: 1/12/2019 Licence: Apache 2.0 """ def login(username, password): # Code here

Even though you may not think that this is important, it can give others some insight into what the file is for, and some other important information such as licenses.

Conclusion

These are only a few specific ones, however, I'd like to see what you use below. As always, I hope you found this useful!

P.S
If you have any suggestions for tutorials, leave them in the comments and I'll be sure to have a look. If you like one in the comments, then give it an up vote to show that you want to see it. It makes my life so much more easier. Thanks in advance!

Voters
Profile icon
AsadAli12
Profile icon
dedo637
Profile icon
frostedbutton75
Profile icon
staticvoidliam7
Profile icon
Vandesm14
Profile icon
abbubakar
Profile icon
SBCKing
Profile icon
TheForArkLD
Profile icon
tgz
Profile icon
TristanMisja
Comments
hotnewtop
Profile icon
Zavexeon

Smh, that's not a comment that's a docstring. Python can't even implement multi-line comments 1/10.

Profile icon
LeonDoesCode

@Zavexeon True, true lul.

Profile icon
SBCKing

The way I see it is your code should only have comments when you are in the middle of something not when it is finished because if you have to add comments to your code then you have written bad code. Your code itself should be explaining itself and comments should only be used in the development phase.

Profile icon
LeonDoesCode

@SBCKing I completely agree, yoir code should be easy to read and follow. I also agree that you should comment your code as you develop it, especially with complicated equations and the like.

Profile icon
Highwayman

Mmm

Sassy.

Profile icon
LeonDoesCode

@Highwayman I try, I try. Lul.

Profile icon
Highwayman
Profile icon
Farrah0987

What are the useful things you get in this code! mapquest directions

Profile icon
staticvoidliam7

i only do comments because my projects are public lol

Profile icon
theangryepicbanana

I feel called out

Profile icon
[deleted]