Posted on

Useful and Useless Code Comments

Jim Nielsen:

If somebody says a comment isn’t adding any value, I would ask: to whom?

Personally, I’ve never liked the advice that writing obvious comments is bad practice—probably because I write obvious comments all the time.

Jim showed off some examples of “code comments that are at the same level of fidelity as the code itself.” Those are the hardest calls with code comments. 

// this function adds two numbers
function add(a, b) {
  return a + b;
}

Easy to point at that and call it not useful. I tend not to leave this type of comment, but it’s fair play for Jim to question that. Comments can be used for a wide swath of people whom may at some point interact with that code, so why gate-keep it?

[…] comments can serve a very different purpose when they’re being read vs. when they’re being written. Those are almost two different kinds of activities.

I’d add they serve a different purpose when re-visiting old code vs actively working. Also different when you’re trying to code review versus directly contribute.

Direct Link to Article — Permalink

The post Useful and Useless Code Comments appeared first on CSS-Tricks.

You can support CSS-Tricks by being an MVP Supporter.

Posted on

Rethinking Code Comments

Justin Duke asks if treating code comments like footnotes could help us understand the code in a file better. In his mockup, all the comments are hidden by default and require a click to reveal:

What a neat idea! Justin’s design reminds me of the way that Instapaper treated inline footnotes.

Instapaper (circa 2012)

I guess the reason I like this idea so much is that a lot of comments don’t need to be read constantly, — they’re sort of a reminder that, “Hey, this needs work in the future” or “Yikes, this is weird and I’m sorry.” Keeping these comments out of the code makes it much easier to scan the whole file, too.

I do wonder if there could be a toggle that shows every comment, just in case you need to read all the comments in sequence rather than clicking to toggle each one.

Anyway, all this talk about comments reminds me of an absolutely fantastic talk by Sarah Drasner at JSConf this year where she discussed why comments are so dang hard to get right:

Direct Link to Article — Permalink

The post Rethinking Code Comments appeared first on CSS-Tricks.

Posted on

Render Snarky Comments in Comic Sans

Hilarious idea by Zach Leatherman. To test if a comment is "snarky" or not, there is an npm package up to the task.

On this site, we generally just delete snarky comments, but I still run a WordPress plugin that allows me to "feature" or "bury" comments. It's old but it still works fine in the latest WordPress. We use the bury functionality for comments that aren't rude, snarky, or spam, but also don't add much to the post. We try to downplay those so they aren't wasting people's time scrolling through the threads.

I dig the Comic Sans idea, so I'm gonna give it a shot. 😉

Direct Link to Article — Permalink

The post Render Snarky Comments in Comic Sans appeared first on CSS-Tricks.