That being said, it's always a good idea to write a manual, about how to use the code. Don't document how it works, because those who can code will understand it anyways, and those who can't, have no need to understand it.

[–] [email protected] 34 points 5 months ago (2 children)

Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.

The code shows what is being done. The comments should explain the why.

[–] [email protected] 14 points 5 months ago* (last edited 5 months ago) (1 children)

Yes. This 1000x. I hate it at work when I come across code that was written 3 years ago that has literally no traces of why it's there and a quick summary of what it does. Especially because that code is always the most abbreviated spaghetti you've ever seen. People should stop thinking (their) code documents itself because 99.999% of programmers cannot do it right.

I really like the Google way of coding: assume the person reading the code is the most 1337 programmer ever, BUT that this person knows absolutely nothing about the project

[–] [email protected] 7 points 5 months ago

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

[–] [email protected] 11 points 5 months ago

This is something a lot of people don't seem to understand. Even if code is self-explanatory, I want to know why it was designed that way.

I've fixed bugs where the fix was only a one line change, but it was extremely difficult to figure out, so I left a 10ish line comment above it explaining why it has to be done that way.

[–] [email protected] 13 points 5 months ago (3 children)

Hard disagree. It's a lot easier and faster to understand a function that is prefaced with a small line of text explaining what it does rather than trying to figure it out yourself.

It's not about whether you can understand the code or not, it's about efficiency and clarity.

[–] [email protected] 7 points 5 months ago

Yeah, just 15 seconds and jot down a comment. Whenever I’m even hesitant, I just leave a comment. Doesn’t hurt anything and it can always be removed if not needed

Easier to remove later rather than add it after the fact

[–] [email protected] -1 points 5 months ago (1 children)

Hard disagree - that's just dumb:

// Calculates tax
function calculateTax() { }

[–] [email protected] 10 points 5 months ago* (last edited 5 months ago) (2 children)

Hard disagree - that's very helpful:

// Calculates Personal Income Tax by formula from section 1.2.3 of tax code. Other taxes like VAT are not calculated.
function calculateTax() { }

[–] [email protected] 5 points 5 months ago

This guy gets it.

[–] [email protected] -4 points 5 months ago (2 children)

If it calculates personal income tax, just call calculatePersonalIncomeTax.

[–] [email protected] 2 points 5 months ago (2 children)

Why not calculatePersonalIncomeTax123 then?

[–] [email protected] 3 points 5 months ago

I'm a new developer. Is that referring to page 123 of the in-house documentation? Version 12.3 of the code? I have no clue.

You'd have to call it something like calculatePersonalIncomeTaxPerTaxCodeSection1_2_3, but I get exhausted just looking at that. There comes a point where the cognitive work of reading crazy long camel case names is more trouble than it's worth.

An explanation of what specification a function was written to implement is a perfectly appropriate comment. Could be improved by a direct link where possible. But it's worth noting what that comment isn't doing - specifying any implementation details. For that, I really can just read the code.

[–] [email protected] 1 points 5 months ago

Yeah, why not?

[–] plecks 2 points 5 months ago (1 children)

Is that state, federal, or combined?

[–] [email protected] 0 points 5 months ago

Add a flag.

[–] [email protected] -1 points 5 months ago

If done right, the "what it does" is in the method name. If your method is too complicated to summarize in its name, chances are good you should split it up or extract parts of it.

[–] [email protected] 9 points 5 months ago

Regardless, comments do speed up understanding.

[–] [email protected] 2 points 5 months ago

Asinine business logic can still make some things very hard to read and digest no matter how well-planned and well-written it is (particularly if it is rushed by the business meaning that engineers don't have time to do it well). As such, there are places where code can't/won't be self-documenting to a useful degree.

[–] [email protected] 2 points 5 months ago

This is true, but it’s easier and faster to parse plain English and so if I don’t adequately comment my code the first time. I will be commenting it when I have to return to it for whatever reason. Honestly the second round of commenting is more verbose and clearer than the function x does y style of comments I tend to make when coding the first time