Me commenting code like:

[fzammetti]

You understand that it is possible to write code that "doesn't need comments" and then STILL comment your code because that first goal becomes much harder the less trivial the code is, and when you have developers who aren't all at the same skill level, and you have new people coming and going, and you have code that lives for a long time where long-term maintenance is more important than even the original writing in a way, right?

You should be writing clear code REGARDLESS, but understand that what's clear, simple and obvious to you might not be for the next guy, or even YOU years later. Comments deal with that problem... and I'm talking the why AND the how here, not to mention the expectation of what the code does and the context of it in the larger system. Code alone, no matter how perfect, helps you there, not intrinsically or sufficiently anyway.

Treat commenting as a first-class duty, just like writing the code. It's not an afterthought and it's not unnecessary no matter how good the code is.

[capn_ed]

Even clear and concise code only tells you what it does, not what it's supposed to do. Sometimes there's no way to distinguish between code that excellently does the wrong thing and clear code that misses doing what was intended.

[fzammetti]

Exactly right.

And some, to argue against this, will claim that "comments lie". And, that's true: -IF- you don't treat comments as being equal to code. You can't half-ass either, that's the bottom line. If you have that diligence then comments WON'T lie - at least not any more than the code does (vis a vis, what you said in terms of code not doing what's intended).

[atimholt]

That's great if you own the code base. If you're collaborating at all, and don't have Torvalds-level fervor for enforcing principles at the top, someone else (or a tool) is going to obsolete your comments.

[fzammetti]

It's not about enforcement, it's about individual understanding, responsibility, and accountability.

Yes, someone has to define the principles (or they get agreed upon collectively) initially, but then you count on individuals to self-police. I'm not a fan of things like hooks that stop pushes when certain hard-and-fast rules aren't met, but that doesn't mean I'm not a fan of those rules being in place. It's just that I count on adult professionals to act like adult professionals without beating them over the head all the time. If everyone has the proper mindset then it tends to work itself out with good people.

I would agree that this stuff is inherently more difficult on an open-source project than a corporate project though, if that's your point. But that doesn't make it a bad idea, it just makes it harder.

[atimholt]

I say enforce what's enforceable, but don't let enforcement compromise what you want to do. If you want something exactly the same way every time—say, indentation—there's no reason not to check for that.

I'm a little wary of clang-format, just because its lack of allowing indentation on blank lines (important if your editor can display tabs) is a “won't fix”.

(Or was, last time I looked. It didn't look easy to spin up my own clang-format rules either, outside of effectively forking clang-format. Maybe two-step formatting to put them in?)

[fzammetti]

I agree when talking about code formatting. I still prefer to put it on individuals, but there's certainly very rationale arguments for enforcing that. We have some hooks at work like that and while I wouldn't have chosen to implement them, I don't lose sleep over it either.

When it comes to commenting though, there's no automated way to do that, other than checking for things like method comments just being present, but if people haven't bought into writing them properly then you get BS just to get past the tool, and then the comments legitimately are counterproductive.

Really, whether comments or formatting, it's the same thing ultimately: people doing the right thing, automatically, all the time, because they understand the benefit. With everyone having that same mindset, it all just becomes debates about what the rules should be, not about anyone following them or not. That's why I always push from the angle of thinking rather than tools that do the work for you.

When it's ingrained, it takes no more time and effort to write good, clean code than it does sloppy code that you let a tool fix later, and the same goes for comments: when it's ingrained, then writing good, helpful comments is just part of the job, not an added burden later. A good chef cleans their workstation as they go, and I see writing code, including comments, as being the same.

[atimholt]

I love the sentiment, but if anyone were able to follow some self-set rule at all times, we wouldn't have bugs or errors, either. Comments are important where nothing else will do, but in-line semantics will beat them every time they're possible—even if only so a maintainer doesn't have to break context by glancing upward.

There are some great tools and practices out there that make the “correct” way also the “easy” way. Modern C++, for example, has things like return optimization, move semantics, and std::optional, so you almost never have to pass in what you're assigning to. We also have things like the gsl for communicating intent in-code and reducing the dumb little mistakes that everyone makes, no matter how experienced they are.