Good Comments for your code[Technique Tuesdays]

This is a mistake that a lot of people make.

Sep 21, 2022

To learn more about the newsletter, check our detailed About Page + FAQs

To help me understand you better, please fill out this anonymous, 2-min survey. If you liked this post, make sure you hit the heart icon in this email.

Recommend this publication to Substack over here

This has been a long time coming,

As some of you know, I have spent a while consulting with groups/teams on improving their projects. Often, this involves looking through their code base to understand specific details and implementations of things they have done.

And well… sometimes the code comments are a problem. While as a general rule- some comments will beat absolutely no comments, having terribly written comments can be a huge hindrance in its own way. In this email/post, we will be going through some commenting practices that you absolutely should follow to skyrocket your trajectory as a developer.

Important Points

Comments are a burden- This is a mindset that I want you to implement. Comments are a burden to you and future developers. They will need to be maintained and updated as you update your codebase. They take up space on your file and increase the number of characters you have to search through. Comments are a burden on your system and adding them blindly is a bad idea. However, you still need them. The ideal to strive for is as few comments as possible.
Replace comments with descriptive variable/function names- This is something I’ve seen a lot (especially with overzealous junior devs that have heard about the importance of comments). They add comments for functions and simple routines. Where you can, replace comments with descriptive function/variable names. If you have a piece of login running a computation store the results (both final and intermediate) in descriptive names that make it clear what your routine does without you needing to add comments for that.
Don’t comment on the what, comment on the why- A lot of the comments I’ve read spend a lot of effort explaining what the code does. Almost nobody explains the why. Spend some time in your documentation explaining what this code does and how it slots into the larger system. This could be in the docstring and/or in your central documentation system (if your organization has one of those).
Explain the inputs and outputs- One of the easiest tweaks that you can make to your docstrings is to explain the inputs and outputs that your function takes. If you have descriptive names, this process becomes very simple. This can help a lot for people looking to understand the processes. One of the single highest ROI changes you can make.

If you start integrating these changes, you will see the quality of your codebase go to the mooooonn. To those that you want to see an example of some of the ideas discussed here, take a look at the following video. The video does a great job on explaining some of these ideas and showing a few practical examples.

I want to understand you better. To help me with that, respond to this survey below. All results are anonymous.

I created Technology Interviews Made Simple using new techniques discovered through tutoring multiple people into top tech firms. The newsletter is designed to help you succeed, saving you from hours wasted on the Leetcode grind. I have a 100% satisfaction policy, so you can try it out at no risk to you. You can read the FAQs and find out more here. Use the button below to get 20% off for upto a whole year.

Get 20% off for 1 year

Before proceeding, if you have enjoyed this post so far, please make sure you like it (the little heart button in the email/post). I also have a special request for you.

Special Request

This newsletter has received a lot of love. If you haven’t already, I would really appreciate it if you could take 5 seconds to let Substack know that they should feature this publication on their pages. This will allow more people to see the newsletter.

There is a simple form in Substack that you can fill up for it. Here it is. Thank you.

https://docs.google.com/forms/d/e/1FAIpQLScs-yyToUvWUXIUuIfxz17dmZfzpNp5g7Gw7JUgzbFEhSxsvw/viewform

To get your Substack URL, follow the following steps-

Open - https://substack.com/
If you haven’t already, log in with your email.
In the top right corner, you will see your icon. Click on it. You will see the drop-down. Click on your name/profile. That will show you the link.

Click on the circled place to get your URL

You will be redirected to your URL. Please put that in to the survey. Appreciate your help.

In the comments below, share what topic you want to focus on. I’d be interested in learning and will cover them. To learn more about the newsletter, check our detailed About Page + FAQs

If you liked this post, make sure you fill out this survey. It’s anonymous and will take 2 minutes of your time. It will help me understand you better, allowing for better content.

https://forms.gle/XfTXSjnC8W2wR9qT9

I see you living the dream.

Go kill all and Stay Woke,

Devansh <3

To make sure you get the most out of Technique Tuesdays, make sure you’re checking in the rest of the days as well. Leverage all the techniques I have discovered through my successful tutoring to easily succeed in your interviews and save your time and energy by joining the premium subscribers down below. Get a discount (for a whole year) using the button below

Get 20% off for 1 year