Hello, and welcome to C++ Weekly. I'm your host, Jason Turner. I am available for code reviews
and on-site training. In this episode I wanted to start a discussion with you, see how you respond
in the comments on the video here. The question is pretty simple - are code comments a code smell?
So it is important to clarify here, and I'm just going to put this at the top of the file
so that we are all aware of the definition - "code smell." We're using this definition
here from Wikipedia: "In computer programming, a code smells any characteristic of the source code
of a program that possibly indicates a deeper problem." So a code smell,
these are the things that a code small is: it is something that might indicate a deeper problem
and should be avoided. It does NOT mean "never do this thing." This comes up every time I use
"code smell." I have someone that comes back and says, "Oh, but in situation x, y, p, q,
we obviously have to do that thing, so therefore your entire premise is wrong."
I'm not saying a code smell means it never should happen in your code,
I'm following this definition. A code smell MIGHT indicate a deeper problem and it's something that
should be avoided. This is something that as you are walking through the code, go,
"something don't smell right here," and you figure out what it is that doesn't smell right. So I've
got this function 'ftw', and now let's just say I've got, like, a for loop of some sort in here.
I've got some widget, and it contains some thingies, and then I've got a function here
that has a for loop as I was saying.
I've got in the most basic case here
this 'ftw' function, and now I'm going to start putting in comments. I'm going to say,
"This function fizzles the widget" (and presumably if you are
in the domain of widgets you would know what that means),
and you've got code that starts to look, I feel like, more realistic than it should.
You've got your function header - it says, "This function fizzles the widget." We've got our 'ftw',
it operates on a widget. We loop over each thingy to make sure the thingy is fizzled to
match the rest of the widget thingies. This, you know in the land of widgets, this does something.
So now the question is, are these comments right here a code smell? I have definitely
interacted with people who would argue that these functions absolutely are code smells.
Their argument would go something like this - if I need a description
for this function to tell me what it does, then the function was improperly named.
So if I name the actual function 'fizzlewidget' (and people who are in the domain of widgets
know what fizzling is), then this function header comment becomes completely meaningless.
Why do I need a function comment telling me that this function fizzles the widget when clearly
this is a function that fizzles a widget? So I can remove that. And now I've got this
thing describing to me that I need to loop over each thingy to make sure that it matches
the fizzling of the rest of the widget thingies. If I were to take this loop,
and I mean, let's let's just say even in the most basic case I did something like this,
now I no longer need this comment, or maybe I don't need most of it. Let's go ahead and
put it back in place here - "Loop over each thingy to make sure the thingy is fizzled
to match the rest of the widget thingies." So I've got this update thingy fizzling, and I can
well, at the moment maybe I can, yeah, let's say I can just remove this. So I can remove this. Now
I don't even need that comment anymore. I've got a simple, straightforward ranged for loop that I am
clearly looping over all of the thingies in the widget that was passed to me, and I am updating
their fizzling. The only comment that's left here is where the actual complex operation happens,
so I might need to explain why 4 is important here; but, you know what,
maybe that in itself indicates that there is a further code smell.
So in a certain world, once we reach a certain point where we have gone through and tried to make
our code as descriptive as possible, we start to ask, "Should we have ever had comments there in
the first place?" So that just raises the question - is a comment in your code a code smell? Does it
indicate that you could have made your code more descriptive and avoided the comment altogether?
So discuss this. Think about it. Talk about it in your teams. Where is the
utility in comments in your code? What comments should be removed in favor of better naming,
or is this all just a silly discussion that we're having right now?