So my GF's studying C#. Some things they learn are actually true 🙈

My linter yells at me if there isn't a description attached to public functions and variables. It's really helped me actually write things down

Bullshit!

Write readable code and use logical names for things.

I have seen too many comments left stale and no longer actually document the code itself. Other times the comments are either just redundant to the code or more confusing to read than the code itself.

My qualifications include over decade of real world experience that academia does not take into consideration.

@CodeMonkeyG while it is true that clean, understandable code without comments is much better than obscure code with comments, it is also helpful to document the general purpose and sometimes pre/post-conditions of library functions. On the one hand, to formally describe possible inputs/outputs, error codes, etc., and on the other hand, for automatically generated documentation, because not everyone will have the source code available for reading.

let y1 = y2 / j3 * b2 // divide y2 with j3 and then multiply by b2

looks fine to me, right?

@CodeMonkeyG @aritzh Totally agree with aritzh. Although readable and understandable code is great, writing proper inline documentation can help a lot if you're in a bigger team.

@balte Not according to Standard.js :P

My definitive opinion is:
"It fucking depends";

@aritzh @lukegv @ScriptCoded
I guess I don't work enough on open source projects.

@Gregozor2121 is right.

I think this is especially true for people new to the field. It had helped me loads compare what I intended to do with what it actually does.

It had also resulted in a bunch of "WTF was I thinking?"

TDD done well results in clear dosumentation, because everything is tested and designed to be tested, i.e. simple, small and readable. The unit tests themselves can be the documentation, for example:

@Test
fun `MainActivity should inflate main_layout upon creation`() {
/* ... */
}

If you don't understand that (because if you change stuff it's bound to break at least one test that neatly describes the intended behaviour), you're a moron. No need for documentation, unless domain-specific terminology or some pattern is used (e.g. for a dependency).

def get_user_by_id(id):
"""
gets user by id
"""

I documented the code, boss.

Was always commenting my code in school. First Pull Request at first job : "Remove all those comments, your code is easily understandable. We don't write comments here at 'company name', as it weighs down the code. You have to write it clear enough so people will understand it first thing."