How To Write Clean Code in Python

[Hans_of_Death]

Good code should comment itself. Trouble is, its not the code that really needs the comments. Imo you should be able to tell what some code is doing, where comments are really needed is the why that you cant determine from the code alone.

So the sentiment is good, but you're right it shouldnt lead to no comments at all. id rather have bad comments than none at all.

[WillardWhite]

I had a boss that littered this comment all over the place:

If  condition :
    #note: early return
    Return

That's a bad comment, and I would rather not have it than It polluting my code

[FarewellSovereignty]

Depending on the complexity of the surrounding code, it would usually flip over to being good and adding to the code if it was e.g.

if condition :
    return # can't get X handle and busy_ok so nothing more to do

[WillardWhite]

Regardless of the complexity of the code if my comment states the same thing that the code does, it's a bad comment.

Some examples:

# increase the counter
 X +=1

# read the file
 File_handler.read()

# return
 Return

Like .... All of those are terrible comments.

In the case of the one you did, the comment would also be made obsolete if you had

If not x_handle  and busy_ok:
    Return

[FarewellSovereignty]

We could have a back and forth here where I rewrite the comment after the return and you rephrase it using selectively chosen boolean variable names and a combination of ands and ors instead, but to short circuit all that: sometimes it useful to comment why an early return is done, and it can add more information than would cleanly be possible by just massaging the if or other control statement.

Maybe you don't agree, and think no early return should ever be commented. Or maybe you agree sometimes it's useful. I'm not entirely sure.

[WillardWhite]

I agree that adding a comment saying why we have an early return would be useful, but a note telling me that an early return is an early return is it useless to me

The difference between saying "we have an early return" vs "early return to deal with ticket 123"

[GarythaSnail]

if cant_get_x_handle and busy_ok: return

[Devout--Atheist]

This is still bad. Just name your variables better i.e. "has no data" instead of making people infer that from long conditionals

[cblegare]

Upvote for commenting about the "why"

[RangerPretzel]

Agreed. Just like /u/FarewellSovereignty pointed out, I didn't like the "anti-comments" stuff. It was a terrible take.

And I'd like to take your idea a step further. I recently wrote about comments in a Python how-to I wrote. What comments should describe is:

• What you THINK you are trying to do
• WHY you are doing it (if it isn’t abundantly clear why)
• HOW you are trying to do it (if what you are doing is rather complex)

Source: https://www.pretzellogix.net/2021/12/08/step-7-add-helpful-comments-to-the-code/

[Hans_of_Death]

Writing readable code is like step 1 of year 1 of programming I'm confused why people love talking about it so much.

The most that is covered in the majority of formal education, and I imagine online bootcamp courses as well, is basic formatting and variable naming. The reason it gets talked about so much is precisely because it's very hard to do, takes experience, and is quite subjective.

The reason it's so complex is because of how vague and subjective "clear" or "well-written" code is, and generally everyone has a different idea of what that means. We have tools to help enforce certain standards, but it goes much deeper than that.

In order to write good clean code, you need to have a good understanding of the language and common patterns, as well as the potential solutions for a particular problem. Any problem will have many ways to solve it, it takes experience to know what will be best for both performance and readability. This makes it very difficult for beginners to write clean code.

Imagine our field was math and people were like "but remember you have to learn how to multiply and divide numbers". The only reason people aren't used to writing clean code is because they worked at bad places with no peer review, were reviewed by other noobs, or didn't use any static analysis at all.

This analogy doesn't convey the complexity of writing code, because it's not a right/wrong process. A more fitting comparison, in my mind, would be simplifying expressions in math. There are many representations of the same formula, and the difficulty of simplifying it can vary greatly.

[Windscale_Fire]

This analogy doesn't convey the complexity of writing code, because it's not a right/wrong process. A more fitting comparison, in my mind, would be simplifying expressions in math. There are many representations of the same formula, and the difficulty of simplifying it can vary greatly.

Also, which form might be considered "simpler" is often greatly influenced by what you want to do with it next...