Apparent Aversion to Commenting

Unreal Courses Talk
#1

I’ve been going through the Unreal Engine C++ Developer course for GameDev.tv on Udemy, and there’s an odd recurring theme I’ve noticed among the three people who have instructed the course thus far (Ben, Mike, and Gavin) is that they have, at least once each, cautioned against creating comments. They each have said that the code should be self explanatory, and thus, should not require comment.

While I am not a professional coder and am not in any position to second guess this particular approach, I do find it odd that it runs exactly counter to what I have been taught from other industry veterans. According to them, you should never assume that code is self explanatory. After all, just because you understand it, doesn’t mean that someone else looking at it knows where you were going with it. Worse, when you look back on your code in a few months, it may similarly be opaque.

My question is this: Why is this course discouraging what I took to be a good coding habit? My knee jerk assumption for discouraging commenting is to avoid comment bloat in your code, but it seems like an overreaction to a smaller, edge case. Sort of like cutting your arm off to prevent a paper cut on your finger from becoming infected.

#2

Perhaps it’s not made clear enough is that it’s a goal for the code to not need comments. Sometimes they are warranted but often you should refactor the code into smaller functions with good names.

Writing good comments is incredibly hard. Comments easily get outdated all the time and now which are you supposed to take as gospel? The comment or the code?

I’ve contributed to Microsoft’s implementation of the C++ Standard library and once or twice I’ve seen a maintainer say something along the lines of “Could you do X? That way we can get rid of the comment” (where X is making the code simpler and easy to understand). For exactly stated above, comments are more fragile than code.

Also this lighting talk at CPPCon goes over how not to write comments

#3

I think that video helped me understand the instructors’ way of thinking on the matter. Thank you for the clarification on this particular perspective.

Privacy & Terms