This comment leaped out at me:
> what is going on in this icky mess
This is a sign that your code is poor, and comments aren't going to help poor code. When you need to comment to overcome poor code, that's a sign your code needs help, not your comments. Thinking comments are going to solve this is a losing game. If this is the way you think, then you'll continue focusing on propping up poor code with comments.
Comments are inherently dangerous. Not because commenting is bad, but because comments are inaccurate. When you write a comment about a block of code, the comment will never be as precise as the code. You'll write about the intent of the code, but even the intent is unclear. The reason for this is with the language we use to write comments. These comments rely on context of the person writing them. And writing is not easy. Describing a block of code that will determine the longitude and latitude is difficult. Do you describe how it does this, the reason it's doing this? Do you talk about how it accomplishes this? Why you are doing it this way? What's important.
For example, take this bit of advice about "good comments":
> A comment should describe the why or the goal, not the how.
So, a good comment would be as follows:
// We accept a search string from the user and transform it
// into a latitude and longitude from the location service.
// We do this because the user knows about where they are, but
// we don't have access to their GPS data at the time, so this
// is a great way to get local data at some level
So, this explains "Why" we are doing this, "what" we are doing, and the goal. However, nothing here is special to a comment over well written code,
public Location getLatLongFromUserLocationSearch( String search );
That does far more, and is more accurate, then the original block of text. More importantly, that original block of text is fundamentally flawed: it's blatantly inaccurate. It also encourages laziness. After all, if your poorly written code is resolved by simply adding a comment, instead of tackling the more challenging part of writing quality code, you take the simple way out of adding in a, most likely, poorly written comment.
> Look, there is what you intend and what you write.
This remark is amusing. Between the two, the chance of a comment being wrong is greater than that of the code. The code is at least tested at some level. The comment is not.
> Don't be lazy
This is an article focusing on writing comments well to cover up for confusing code? The assumption here is that it's easier to write comments well. I'm sorry, but if you can't write the code cleanly in the first place, how are you going to effectively write a comment that will clear things up.
> You're a Journeyman
Damn right, and I know that there are far better avenues than writing comments in code to accomplish that. On top of this, the example is absurd, as he's suggesting not limiting what your comment includes to what and how, but also why: "Tell them why you choose to use a Tuple in this case."
> So you type 40 - 60 wpm. So then tell me again why aren't you writing comments while you blaze through your code?
Oh, the travesty. To equate typing speed with quality. And make no mistake, that's what is being done here. Somehow, typing speed is the issue. It's akin to relating line count to performance. Listen, typing speed isn't the issue. It's quality, and quality takes time. Writing quality code is not defined by your typing speed. Neither is writing quality comments. It doesn't take a long time to write quality comments because you lack typing speed, but because writing clear comments is hard work.
> You're going to get old
If you weren't clear that an ego the size of Jupiter was writing this post, this section will slam the point home.
First, let's get this out of the way:
"I've been doing this for a while, probably before you entered middle school."
Your age does not qualify you. Bringing it up again and again only means it's the best qualification you've got. Wisdom isn't about age, though age gives you more opportunities for obtaining wisdom.
As for getting older, there are far better mechanisms for ensuring that you know what the intent of the code is, from both a business sense, and from a code sense.
Honestly, the biggest warning to relying on comments to resolve deficiencies in other areas is this article itself. It's poorly written, confusing, and even contradicts itself.
In the end, it's some of the same tired advice presented in a brash way. This brash method, employing vulgarity and rudeness, fails. "Comment your damn code because I said so and I'm old and that makes me right" is essentially what it amounts to.
I'm harsh, James, because your article is harsh. It preaches writing comments, and does so in poorly written English.
In the end, commenting your code is the worst thing you can do.
Commenting your code well, however, is not. But commenting your code well is a challenge. It's not easy, and should not be seen as trivial.
Well written code takes longer than 30 seconds to write. Well written comments take longer as well. And well written comments in well written code are not added every 3 to 7 lines.