Let’s talk about comments.

There are a lot of varying philosophies about comments and when and how often to write them. Some people think comments are good, some people think comments don’t belong in code at all. I don’t think I’m telling anybody anything they don’t already know when I say: the right approach is somewhere in the middle.

But that’s not fun to write about. I present to you:

Top 10 Problematic Comments

I started writing this article with a serious tone. I have now abandoned that. Most comments are reprehensible. These comments are the worst. They’ll rot your code, infect your repository, and keep your company from competing in the marketplace. If you see comments like this in your code, delete them immediately, then make a pull request. And then cite this article when the reviewer complains.

hahaha. from the desk of my friend! and by desk i mean from the pieces of his broken dreams.

1 Like

Interesting points:

The whole idea of commenting every line dates back to a time when languages were inherently hard to read. We don’t live in that world now, languages are better, they’ve evolved to a nice middle ground where they are readable by computers and humans. Get with the times.

I hadn’t considered that. I’m not sure how I can explore the notion.

We all use revision control now. What is the point of putting creator and created-at date at the top of a file? All that information and more is recorded in revision control.

That’s a good point: put info in the header that folks unable to use a version control system will find useful. An email address might be appropriate, say for a steward of the code.

I’ve never seen a text editor in my life that didn’t display the name of the file prominently at the top of the window. We don’t need a comment at the top of the file. Who does that help?

I have, and this supports the first interesting point regarding evolving practices.

1 Like