Writing in-code comments is code smell?

8Responses

Write your response…

This answer has received 3 appreciations.

it depends.

the what should not be commented at all for example

func main() {
    // gets dictionaries
    d := get();
}

func get() {
......
}

it rather should befunc getDictionary()

that's actually a good point to be made for "don't comment things that you actually just could name appropriate" that's a code-smell right there.

but you should comment the "why" if it's unclear on the context.

func main() {
    // using do while because it always has to run at least once
    do {
    } while (i < 0)
}

there are ofc things like decisions that had to be made because a certain API you implemented against.

func main() {
    foo := getMyDataFromTheApi();

    // needed to be done because of blub
    if (foo["certain_field") == "certain condition") {
        foo["certain_field") = null;
    }
}

so this would be a common pattern we see, which is okay as long there is only 1 change but lets be real .... code evolves and soon there will be other comments in the same context that's why we should do the following

func main() {
    foo := cleanupTheApiDataBecauseOfReasons(
        getMyDataFromTheApi()
    );
}

// we now comment outside of the code but still 
// the functioname is clear. That's what we want
// and we encapsulated the issue in a clear manor
func cleanupTheApiDataBecauseOfReasons(foo) {
    // needed to be done because of blub
    if (foo["certain_field") == "certain condition") {
        foo["certain_field") = null;
    }
    return foo;
}

so I think it's always about context, but if I can I follow those patterns because they are easier to read .... in experience most devs don't read comments or the documentation ... but we read the code so naming the functions and code verbose helps more than putting to many comments into the code.

That's at least my opinion.

Write a reply...

Code smell? Haha, I love coders and their views on coding life. I'm sure your colleague likes to work alone and not in a team. But even when working alone all the time, in-code comments are a great tool to document classes and methods, give insights and write messages to future you and others.

By the way, nowadays, when using compilers, transpilers or any kind of automation tools ,one can just filter out comments during compilation, so what's the big problem?

Indeed, it's very handy to see what type the params are in comments, so that I don't have to claw through the actual code to find out. In that sense, even open code is a kind of black box.

Relying on code to explain your code seems not the way, but if the actual code is unreadable, then please do have as many comments as possible. The problem is most of the time that there are no comments at all.

Write a reply...

Code should be self explanatory. The reasons behind the code are not always self explanatory. In a couple of years it will probably be forgotten why some code was needed. I prefer to work with people who do a good job documenting code. It's not just me either. Javascript frameworks with good documentation often see better adoption rates than those without good documentation.

Agreed, but if it isn't self explanatory, then please do add comments!

Write a reply...

Unnecessary comments do indeed clutter things up and could be considered code smell, especially when what's being commented is obvious. Sadly, those who do this commenting were conditioned to by their professors when they went to school. I've noticed more unnecessary commenting coming from those who went through schooling vs. those who are self-taught.

That said, comments are necessary when it's not obvious what the code does. Personally, I also comment when changes are made in the code. For example, I might put in:

// 10/11/2017 JLC - Added to support X feature

Datestamping the comments is immensely helpful because then I know when a certain change happened. Changelogs are fine, as are commit comments, as they are datestamped, but putting the date and by who just above where the change occurred can help jog my memory as to why a change happened. At that point, it's just a matter of going back to email to figure out what was really being asked for. It's happened many times where I'll get asked why a certain behavior is happening, I'll see this, correlate it to an email exchange, then say to the person: "Because you requested it back on XXXX date. Check out our email exchange that day." The issue typically gets dropped after that. :)

Write a reply...

+100 to chilimatic's reply, naming stuff properly trumps comments every time, over time comments become white noise or wallpaper which you will tune out or not notice, especially as most IDEs colour comments so as to be less prominent than the actual code.

The best comments are additional to well named and structured code and form part of your docs so are in consistent form and style

Write a reply...

That makes sense.

As an old-school coder I agree that the more you write comments the better. So ideally every block of code should have some short or long explanation in the comment above.

But when you are working on a live and commercial project, spending so much time to polish your skills in literature during writing long comments may not be wise. The reason is not that you become irresponsible or anything, it's just you know your team. So most of the blocks are obvious and your teammates can easily read it without comments. So no need to spend your time on that, you'd better continue your work on other blocks. Of course it doesn't mean that comments completely vanish, there will always be some. And when you see one, it means that the code below is not trivial, otherwise there wouldn't be a comment.

I try to leave comments in all places where it needs an optimization/refactoring but, of course, not now. Usually when I add (N+1)th small feature. Eventually when a team member (or myself) during refactoring ran into a comment, he'll know that the code below should be read carefully, to prevent breaking something after refactor.

When you are contributing to an open source project it's a completely different story. In the Open source world a comment has a different smell. In an open source project there are lots of contributors (team members). An experienced contributor tend to write comments. And you should always look up to more experienced people than yourself.

Write a reply...

I can see where your colleague is coming from, but I think their viewpoint is on the extreme side of the scale. To me it sounds like they're thinking along the lines of: "this person wrote a comment, therefore they probably have a misunderstanding about the code that follows, so they might have written error-prone code". Equally, they might have completely understood the code and simply want to help other developers get a quick summary of what follows. It may or may not be of any actual help to themselves or others, but this is simply what some folks like to do.

There's other common uses for comments too, such as for automated documention tools and to simply help break up blocks of code with clear divisions.

Write a reply...

Oh, so your colleague thinks the Linux kernel programmers create smelly code, huh?

I'd love to meet this guy/gal. I have high expectations. I'd also love to hear what Linus Torvalds feels about this.

On a more extended and personal note, here's the low-down on how I feel: People have opinions. Some coders feel like readability is priority. Others, efficient use of space, still others, efficient code performance...

Some coders also make blanket statements like "GOTO SHOULD NEVER BE USED EVER." or "SCANF IS DANGEROUS AND SHOULDN'T BE USED."

I generally disagree with folks who make generalized, blanket statements like this and I find those people to be misinformed, egotistical, or simply not very bright. The reason being, all of these constructs were created for reasons. To say the creators of languages were facilitating code smell by allowing for comments is absurd. I don't care how well you name your functions/methods and fields/variables, you simply cannot express everything that way. There are reasons for comments to be used and I trust that brilliant folks like Dennis Ritchie, Ken Thompson, Anders Hejlsberg, James Goseling, etc.... Knew this rather than your coworker who just doesn't like something and labels it as completely wrong. Hell, even Uncle Bob Martin, author of Clean Code, promotes comments where necessary. I'd like to read a book by your coworker with more info on this belief.

Write a reply...

Join a friendly and inclusive Q&A network for coders

  • 🖥Pick the technologies you like & read great content through your feed.
  • 💬Ask a question when you want to learn more about anything.
  • 🚀Share what you know & build your portfolio.
Sign up nowLearn more

loading ...