Code review:

- Almond: This method here is a mix of convoluted loops conditionals and ternaries... I really don't think we can pass this. Can we make sure this logic is a lot clearer?
- Bob: Oh, ok, sure. I'll work on that.

Next day:

- Bob: I've hopefully cleared up the meaning of that code now.
- Almond: Sure, let me look. Err... it looks the same to me? Have you done it in another branch?
- Bob: Oh no, it is the same, but there's a link in the code now to a PNG of a flowchart I put together in draw.io to show how it works.

...🤦‍♂️

🤦‍♀️

Someone needs to slap Bob 🧑‍💻👋

It's moments like this I don't regret having a nerf gun in the office.

@molaram i was thinking more like Archer

Just... What the fuck. How can someone think that's ok to put in a comment? There's some stupid people on this planet, but Bob might've won the trophy...

@M1sf3t in conclusion, bob is retarded

You can't make this shit up...

This is why my work frowns on commenting code. If you need to explain your code it's probably too complicated

What the hell everyone! Bob clearly made an effort to get his point through! Only OP knows what that code and flowchart had. Are you people telling me there it's not just as plausible that Bob's flow chart could actually illuminate his code and why he had to write it that way?
Based on the info given by OP there's no rational way to assume he made a mistake or not.

@OneOfSimpleMind why the reaction? because appropriate action is following:
a) decision logic within code should've been simplified or at least its readability improven
b) documentation (incl. decision trees) belongs to documentation, not code comments

@M3m35terJ05h lolwut

@Maer Readable code. Instead of saying what one part of a function is doing in a comment, you take that code and put it in its own function with a name that says what it's doing. I was a bit iffy at first but actually this codebase is stunningly easy to work with. Obviously this doesn't apply to public facing parts of a library or api

@M3m35terJ05h Importantly, that approach also makes unit testing far easier.

@M3m35terJ05h

Yes, I understand about code being readable, however wholesome discouragement of comments in code makes equally no sense and is not recommended anywhere.

There will always be code passages where it is helpful to the reader if they have extra info in addition to the code, even if it just to make them understand code faster.

In addition, commenting functions and their parameters is also part of code comments and is absolutely crucial. Why would anyone discourage developers from doing that?

Code that is so convoluted and badly written that it requires a novel spread over the whole file to be understood is obviously awful. However code that lacks comments completely, because "my design is so crystal clear and everyone *has* to understand each line, as we all share a completely equal knowledge base" - that's 100% just as bad.

@Maer Dunno what to tell ya. Cleanest code I've ever worked with. If we had doc comments they'd be on average as long as the functions they're documenting. I'd rather read the code. If I even need to go that far. It's more accurate. Seriously, why bother approximately translating code to an audience that can read code.

Like, I get it if you're doing something out there like that fast inverse square root hack in doom. But that's not applicable to my job

@M3m35terJ05h

They way we typically go about this is providing comments for function signatures, i.e. Doxygen style documentation about what the function expects the parameters to be.

Other than that the functions are typically devoid of comments, unless a line warrants specific explanation, this is usually the case if a line has to be written in an unexpected way, due to some specific circumstances. E.g. usage of an external API which requires an unexpected, non-intuitive order of calls to initialize properly.

@M3m35terJ05h

One reason is typically to provide an API. When I want to merely use your function in my code, I don't necessarily want to read what it does exactly. All I want to know is what kind of input it needs and what kind of output it produces.

Possibly you are writing functions that are very small, so that a function is never more than 3-4 lines? If this was the case, then you obviously produced more function signatures which at this point then become your documentation. This is just a guess though.

Still, even when omitting all comments from function bodies - I see no reason not to add documentation to function signatures.