🦥 How To Write Good Code Comments

Sponsored by

Hello friends!

Welcome to another late issue of Sloth Bytes (whoops😅)

Start learning AI in 2025

Everyone talks about AI, but no one has the time to learn it. So, we found the easiest way to learn AI in as little time as possible: The Rundown AI.

It's a free AI newsletter that keeps you up-to-date on the latest AI news, and teaches you how to apply it in just 5 minutes a day.

Plus, complete the quiz after signing up and they’ll recommend the best AI tools, guides, and courses – tailored to your needs.

Sign up to start learning.

A female sloth will have 1 baby approximately every 2 years.

Code Comments

Ever stared at your code from 6 months ago thinking “why did I write this garbage?”

You probably left some comments that weren’t necessary or didn’t leave a comment at all…

Let's fix that problem by talking about how to write comments that actually help future you (and your team).

The Golden Rule of Comments

❌ Explaining what the code does

✅ Explaining why the code does it

Comments That Hurt More Than Help

// Increment counter by 1 (pretty obvious...)
counter += 1;

// Loop through array (also pretty obvious...)
for (const item of items) {

These comments… well

They serve absolutely NO PURPOSE.

The code already tells us what it does!

Comments that actually help

// Rate limit: Maximum 100 requests per minute per user
const THROTTLE_LIMIT = 100;

// Skip validation in test environment to improve test speed
if (!isTestEnv) validateUser(user);

// Reverse the array first to handle nested dependencies
// Example: C depends on B, B depends on A
tasks.reverse().forEach(processTask);

When to Comment (And When Not To)

Comment when:

• Explaining business logic that isn't obvious

• Documenting workarounds or gotchas

• Warning about edge cases

• Explaining "magic numbers"

• Clarifying regular expressions

Don't comment when:

• The code is self-explanatory

• You can make the code clearer instead

• You're commenting out code that you won’t use for a while (use version control)

Better Than Comments: Self-Documenting Code

❌ Poor names + comments:

// Check if user can access feature
// u = user and f = feature
function check(u, f) {
  return u.p.includes(f);
}

✅ Clear names (no comment needed):

function hasPermissionForFeature(user, featureName) {
  return user.permissions.includes(featureName);
}

Comment Checklist

• Would this be comment unnecessary if the code was clearer?

• Will this comment still be true in the future?

• Does it explain the "why" not the "what"?

• Is it up to date with the code?

• Would you want to read this comment?

Remember

• Comments are a last resort - clear code is better

• Keep comments close to the code they describe

• Update comments when you update code

• Delete comments that no longer add value

• Write comments like you're explaining to your future self

Pro Tip: Use keyboard shortcuts in your IDE to toggle comment blocks quickly.

In VS Code:

• Windows/Linux: Ctrl + /

• Mac: Cmd + /

Now go and fix your comments. Your future self will thank you.

Instantly add file uploads to your app with Pinata’s API

Pinata’s File API lets developers integrate file uploads and retrieval in just minutes. No complex setup, no configuration headaches—just fast and scalable file management.

Start building!

*A message from our sponsor.

Thank you to everyone who submitted 😃 

There was a lot of submissions this time.

joshuahighley, RelyingEarth87, cheodoor, Saydfalls, pyGuy152, JamesHarryT, sonvalle, trgr-boi, ravener, tobiaoy, and many more (sorry got lazy!)

Is the Phone Number Formatted Correctly?

Create a function that accepts a string and returns true if it's in the format of a proper phone number and false if it's not. Assume any number between 0-9 (in the appropriate spots) will produce a valid phone number.

This is what a valid phone number looks like:

(123) 456-7890

Examples

isValidPhoneNumber("(123) 456-7890")
output = True

isValidPhoneNumber("1111)555 2345")
output = False

isValidPhoneNumber("098) 123 4567")
output = False

Notes

Don't forget the space after the closing parenthesis.

How To Submit Answers

Reply with

• A link to your solution (github, twitter, personal blog, portfolio, replit, etc)

• or if you’re on the web version leave a comment!

That’s all from me!

Have a great week, be safe, make good choices, and have fun coding.

If I made a mistake or you have any questions, feel free to comment below or reply to the email!

See you all next week.