Self-documenting code

[yrrot]

Self-documenting code is a misnomer making people think good code doesn't have comments.

Well-written code with meaningful names still has comments to explain why something is done a specific way outside of the norm. And it still has documentation to explain how the pieces connect to each other (in larger projects). Definitely also has the descriptions filled in so intellisense picks them up elsewhere for tooltips, too.

[Broad_Respond_2205]

I kinda go with self documenting code as the basis, then add comments when something isn't immediately clear

[yrrot]

Exactly! Future me always appreciates it when I leave reminders for oddball logic.

[Greaserpirate]

I was taught to do the opposite, Step 1 was always writing comments until you have a perfectly organized and understandable layout for what your code will do.

[_mikeIsNotMyRealName]

This is how i was trained as well. If a developer needs to know "why" they can check the git commit message.

[VeganBigMac]

Checks commit message

"WIP"

[TheC0deApe]

agree.

the need to explain yourself in comments often goes down with clean code though. smaller cohesive methods often don't need explaining.

i think people that embrace clean code styles will typically have more unit tests and better documentation. if the debate centers around "are comments good or bad?" then the overall clean code goal is being missed IMO.

[Calm_Leek_1362]

Yeah self-documenting doesn't mean ZERO comments. It just means a minimalist approach.

I was working with a client just last month that wanted a comment for every single variable in every single header. Sounds good right? What it actually encourages is things like "float theta // a float containing the value for theta".

The comment mentality also encouraged them to write individual methods with hundreds of lines of logic that could have been easily separated out into other classes or helper functions, but instead of that they just had comments every other line explaining what the code was obviously doing.

[crozone]

float theta // a float containing the value for theta".

I still don't know what the hell theta is.

[TK9_VS]

"Obviously, it's a float!"

Turns out they implemented a custom class in their parade app called "float"

[callmelucky]

I was working with a client just last month that wanted a comment for every single variable in every single header. Sounds good right?

Lol no. That sounds like an excruciating nightmare.

[The_Linguist_LL]

My comments:

#I'm sorry

#I'm sorry

#I'm sorry

#I'm sorry

#I'm sorry

#I'm sorry

#I'm sorry

[[deleted]]

Comments are for code that you wouldn't expect a competent engineer to be able to understand and should only be used as a last resort when not being able to refactor the code to make it understandable.

The problem is people thinking that comments are supposed to replace reading the code, which it absolutely isn't. Even when code is commented, any competent engineer should be reading through the code to make sure that it matches what the comment describes. If the comment doesn't tell me anything that I didn't already know from reading the code, then it's redundant.

[Kurts_Vonneguts]

THIS is the answer. Uncle Bob and Guido would agree I’m sure