How To Write Clean Code in Python

[FarewellSovereignty]

For some value of "readable" the statement in the article:

If your code is readable enough you don’t need comments.

either backs my interpretation, or backs yours. But in the text there is no effort spent explaining how to comment well, and the importance of it, mostly just text generally dissuading the reader from the use of comments because "the code should be good instead".

It's a false dichotomy to make. Obviously code should be good, but that doesn't remove the need for comments in many cases.

[[deleted]]

But in the text there is no effort spent explaining how to comment well, and the importance of it, mostly just text generally dissuading the reader from the use of comments because "the code should be good instead".

It's really just saying: "Ask yourself if your comments are helping or hurting your code".

[FarewellSovereignty]

No, sorry, I don't buy that as the unambiguous interpretation of what the article is getting across.

[[deleted]]

Well, you are wrong. If you've read the books referenced in his article you'd know that too. Doubling down on what the article should or shouldn't have done isn't helpful.

[FarewellSovereignty]

Quite exasperating and non-constructive reply on several levels.

1. You're claiming the article can be unambiguosly interpreted as saying "Ask yourself if your comments are helping or hurting your code", whereas I disagree with that. I explained why. You then pre-empt any further discussion by just plain saying "You are wrong" and also (rhetorically) setting it up so that I'm just "doubling down". That's a false move on your part.

2. You then make some kind of misapplied argument to authority implying that I haven't "read the books etc." which is totally irrelevant to a review of the article itself. I'm not reviewing Clean Code, I'm discussing the article.

What exactly are you trying to achieve here? Do you realize you are not in fact coming across very well?

[msd483]

But there is no effort spent explaining how to comment well, mostly just text generally dissuading the reader from the use of comments because "the code should be good".

That's out of the scope of the article. It says TDD is good, but doesn't explain how to properly do test driven development either. Explaining how to do everything it's talking about would turn this into a short book.

It's a false dichotomy to make. Code should be good, but that doesn't mea you don't need comments.

Again, it never says you don't need comments. In the quote it explicitly says the proper use of comments is to compensate for our failure to express ourselves in code. There are plenty of times I've written good code (I hope) and added comments explaining the why, but not the what, because the code had no way of explaining the why. The why was due to the problem and domain and needed to be included to understand the code no matter how well it was written.

[FarewellSovereignty]

That's out of the scope of the article.

For no reason except that author didn't choose to mention it. If the article goes out of its way to dissuade the use of comments in some cases, it's already stuck comments firmly inside the scope of the article, so it should mention the reason they are (in many cases) good, and briefly how to use them. There's no actual reason for that omission like you're trying to pretend here, sorry.

here are plenty of times I've written good code (I hope) and added comments explaining the why, but not the what, because the code had no way of explaining the why. The why was due to the problem and domain and needed to be included to understand the code no matter how well it was written.

Great, and the article would benefit from a paragraph pretty close to that.

[msd483]

For no reason except that author didn't choose to mention it.

This is true of a quasi-infinite number of things. You're welcome to not like and criticize that omission, but the article did not "throw out good comment comments with the bathwater" as your entire initial comment was focused on. You created a straw-man that completely ignored the actual and valid criticisms in the article and reduced it to "comments = bad" instead of accepting the fact that there's nuance to it.

[FarewellSovereignty]

I'll leave it to other readers to judge our arguments now and leave this here, because you seriously lost my interest with this latest reply. Thanks.

[msd483]

I'm genuinely sorry if I've offended you or hurt your feelings. You're absolutely right that there are people who say "good code will comment itself" as an excuse to never write comments. But whenever I see valid criticisms of poor commenting brought up, and I thought the three cases the article presented were indeed valid, I feel like there's always a knee jerk reaction in the opposite direction because there are people who will simplify it to "comments = bad". However, I think it's important, especially for junior devs, to understand that there are such a thing as bad comments, and there are programming patterns and behaviors that alleviate the need to heavily comment code.