Commenting Your Code
LeonDoesCode (272)

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!

You are viewing a single comment. View All