Write Better Code Comments: A Developer's Guide to Clean Code

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.

Giphy

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.

Devin is now generally available (8 minute read)

Devin is now available to take your jobs for $500/month

Sora is Now Available (3 minute read)

Sora is out! You can use it at sora.com⁠ if you’re a ChatGPT Plus and Pro users.

ChatGPT Pro (4 minute read)

A $200 monthly plan that includes unlimited access to OpenAI o1, as well as to o1-mini, GPT-4o, and Advanced Voice. It also includes o1 pro mode, a version of o1 that uses more compute to think harder and provide even better answers to the hardest problems.

Meet Willow, Google’s state-of-the-art quantum chip (9 minute read)

This new quantum chip demonstrates error correction and performance that paves the way to a useful, large-scale quantum computer.

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.

Which IDEs do software engineers love, and why? ( 16 minute read)

Software engineers shared their favorite IDEs on social media.

Driving a Project: Intern Edition - Engineering at Slack ( 7 minute read)

After a lot of hard work, you’ve landed that coveted internship. Now comes the next big challenge: delivering a meaningful project over the summer.

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.

🦥 How To Write Good Code Comments