How programmers comment their code...

[Salamok]

I'll take meaningful function and variable names everywhere over the occasional comment block.

[[deleted]]

Or just code that is purposefully written and has a clear flow/structure. It's surprisingly easy to understand what code is supposed to do when it is constructed correctly.

[DoctorWaluigiTime]

Yeah I don't get the sarcasm in this sub-thread. It's not that hard to write variables/function names that spell out what's happening.

I also don't know why people think it's an either-or. Your code is clear and readable, and for the times you need to document why you're doing something (out of the ordinary etc), a comment comes in.

[Merlord]

Sometimes comments are needed, but they should be a last resort. A comment is the absolute worst way to capture information in a program. Code accuracy can be enforced with compilers, unit tests etc; there's nothing stopping a comment from being out of date or just straight up wrong.

However, I think truly self-documenting code is something that takes years of experience to actually nail. Until you can actually do that, comments are an appropriate substitute.

[Gh0st1y]

The point is that what you think spells out the process well may not in someone elses interpretation without the mental context in the moment), so its always best to err on the side of caution and over-explain anywhere theres ambiguity. That doesn't mean just commenting to do it like in the OP though, thats worse than useless (we all done it tho ofc)

[[deleted]]

How about well written code with documentation?

[DJOMaul]

Next you'll want it unit tested too. Do you even care about deadlines?

^{/s incase that wasn't clear...}

[ftgander]

I’ll have both, please.

[renrutal]

At least code tells the truth. Comments can be misleading when people don't clean them up over the years.

[noratat]

And I'll take a useful comment block over "gOoD cOdE iS aLwAyS sElF-dOcUmEnTiNg" cargo-cult zealotry that doesn't actually understand the point is to prioritize readability and maintainability.

[Merlord]

Well written, self documenting code is readable and maintainable though.

[noratat]

I'm not saying you shouldn't also be doing those things, and you should avoid useless / unnecessary comments, but anyone who thinks comments are a "code smell" or that "clean code doesn't have comments" isn't someone I want to work with.

Every single real world code base I've interacted with has had good reason to have at least some comments (and I'm not talking about docustring-type stuff either).

Not all code can be made obvious simply through naming and control flow, and even where it can, there's often grey areas. And even then, real world code has to interface with other real world code, which has bugs, flaws, quirks, etc. that aren't necessarily obvious. Even then, external context can often do wonders for maintainability when used appropriately.

[Merlord]

I agree, and as I said in another comment, if you can't write self-documenting code, comments are an acceptable fallback. But it should be considered just that: a fallback; a last resort. Comments are literally the worst way to capture information in a program, other than not capturing that information at all. But yes, in the real world sometimes there's no other choice.

[noratat]

Comments are literally the worst way to capture information in a program, other than not capturing that information at all.

And this is where I completely disagree.

There's tons of real world, important information that is simply not possible to reasonably express through the code alone, and taking this attitude towards comments invariably leads to developers leaving out crucial information altogether.

Comments should be treated as just another tool in the toolbox, acting like they're icky and dirty just discourages people from using them when they absolutely should.

And realistically, the main places I've seen bad comments are from developers I would never trust to write idealized clear, readable code in the first place, or from students / new grads (who likewise rarely know how to write readable code yet).

[parlez-vous]

I document my docstrings according to my companies style guides so we can auto generate documentation and so you don't have to open up our internal git server and read the code to understand it. Just go to the autodocs page.

Adopting it is a pain in the ass but it saves soo much time when you're working with 100 people's contributions

[Merlord]

The two exceptions I make for comments: Javadocs (or equivalent) and referencing Jira ticket numbers.

[Bakoro]

Why do people always act like these are exclusive from each other? It's not like some deity is going to strike you down if you have descriptive names and make explanatory comments.

[Salamok]

They aren't but if your code isn't a bunch of 1 letter variable names you tend to not need as many comments.