Do code comments suck?

A conversation about comments.

Sam Fare
Sam Fare
Aug 2, 2018 · 4 min read
Image for post
Image for post
“Close-up of a person's hands on the keyboard of a MacBook” by Glenn Carstens-Peters on Unsplash

What is a comment?

What’s the point of that?

So comments help us clarify our code?

That sounds like a good thing…

So what makes comments ‘the worst’?

Image for post
Image for post
Some code with a hidden comment.

So why not just write a blog called ‘Please Read Comments’?

Well no, it’s an easy thing to forget.

Ok I accept, comments aren’t perfect. Nothing in this world is. Are you saying you have a better plan?

What about a comment that describes what a variable is, are you saying that it isn’t good to clarify what your variables are for?

This applies to functions too doesn’t it?

So what about your code from earlier, those comments describe blocks of code that achieve functionality together. That can’t be helped by good naming, can it?

So what about if I have to heavily optimise some code, can I use comments then?

Wait, what?

So comments are good?

Compare the Market

The people behind comparethemarket.com and the Meerkat App

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store