I have such a love-hate relationship with that video. On the whole, I think that video is bad and should be taken down. The creator is arguing against a very specific type of commenting but is harassing comments in all forms. It even addresses as such with a 20 second blurb 2/3 of the way into video distinguishing between “documentation comments” - but doesn’t really provide any examples of what a good documentation comment is. Just a blurred mention of “something something Java Doc something something better code leads to better documentation” but doesn’t elaborate why.
It’s a very devious problem in that I don’t feel like any particular claim in the video is wrong, but taken within the context of the average viewer, (I teach intro. comp. sci courses and students LOVE to send this video and similar articles to me for why they shouldn’t have to comment their spaghettified monstrosities), and the inconsistent use of comments vs. code duplication vs. documentation, the video seems problematic if not half-baked.
In fairness, it is great advice for someone who has been working in the industry for 15 years and still applies for junior positions within the same company - but I can’t imagine that was the target audience for this video. In my experience, anyone who has been programming on a large-ish project for more than 6 months can reach the same conclusions as this video.
I’m from the camp that thinks if you’re trying to make a case (about any subject), you should start with your strongest point and work to your weakest point. Every argument I’ve ever seen against code comments starts off with the weakest imaginable points. Usually the first point made is sample code like “x = x + 1” with the absurdly unnecessary comment “add 1 to x” - as if that’s ever something that pro-comment programmers do. This video at least started off with a novel weak point (somebody using a comment with a magic number instead of making it a constant) although it’s just as weak as the “x = x + 1” argument.
I have such a love-hate relationship with that video. On the whole, I think that video is bad and should be taken down. The creator is arguing against a very specific type of commenting but is harassing comments in all forms. It even addresses as such with a 20 second blurb 2/3 of the way into video distinguishing between “documentation comments” - but doesn’t really provide any examples of what a good documentation comment is. Just a blurred mention of “something something Java Doc something something better code leads to better documentation” but doesn’t elaborate why.
It’s a very devious problem in that I don’t feel like any particular claim in the video is wrong, but taken within the context of the average viewer, (I teach intro. comp. sci courses and students LOVE to send this video and similar articles to me for why they shouldn’t have to comment their spaghettified monstrosities), and the inconsistent use of comments vs. code duplication vs. documentation, the video seems problematic if not half-baked.
In fairness, it is great advice for someone who has been working in the industry for 15 years and still applies for junior positions within the same company - but I can’t imagine that was the target audience for this video. In my experience, anyone who has been programming on a large-ish project for more than 6 months can reach the same conclusions as this video.
I’m from the camp that thinks if you’re trying to make a case (about any subject), you should start with your strongest point and work to your weakest point. Every argument I’ve ever seen against code comments starts off with the weakest imaginable points. Usually the first point made is sample code like “x = x + 1” with the absurdly unnecessary comment “add 1 to x” - as if that’s ever something that pro-comment programmers do. This video at least started off with a novel weak point (somebody using a comment with a magic number instead of making it a constant) although it’s just as weak as the “x = x + 1” argument.