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...

Load more responses

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 ...