Is it worse to over comment or under comment your code?

Under comment is the worst

I'd say over comment is worse personally, especially if taken to the extreme. But both are bad, it's not really a contest.

@AlmondSauce If you do not comment over or under your code, you will realize after some years when you open that code for update or anything else.

Too few comments is worse because you can always delete too many comments later, but what isn't there will always be missing.

It's not really what the code is doing, that should be clear enough from the coding and naming style, but why it is the way it is, or why another, more obvious way wouldn't work.

That goes in particular for any abstraction leaks, i.e. where shit from other layers has impact although that wouldn't be expected in an ideal world.

From a different point of view, the outlook is wrong. Comments are a way of saying 'i couldn't write self explanatory code so I gave up and wrote a comment that hopefully won't get too old to be useful'.

Over commenting or under commenting, this suggests some level of commenting is wanted.

(Obviously everyone adds a comment sometimes because no one does a perfect job)

Comments that don't add anything that can't be easily read from the code. Also, comments that are wrong.

@Fast-Nop The problem with over-commenting isn't that it's just a bit verbose though, the issue is that those comments inevitably don't stay correct, or some aren't even written correctly to begin with (and that's rarely checked, since everyone understands the motivation at the time of writing.)

I've been caught up in rewriting more than one heavily-commented legacy project where the comments were beyond useless to the point they threw us off completely - they were making various incorrect assumptions about both the business requirements & the code flow, and that caused a great deal of confusion across the board. They weren't *all* bollocks, but that just made it worse, as we didn't know what to believe.

If that commenting had been kept just to the important bits that actually *needed* commenting, it would have been a way easier task to unpick the mess.

@AlmondSauce No shit, you have to update documentation during the lifetime of a project? And the solution to avoid that is, ideally, no documentation, or at least as little as the devs can get away with?

How about we extend that to the names of variables, functions, and classes? They also get out of sync with their names, so let's just use three characters at most for everything.

You see where that's going. The solution to sloppy documentation handling is not discarding documentation, but doing it properly.

Doesn't have to be as code comments, but if devs are already struggling with keeping comments in the same file up to date, there's no reason to believe they could sync their code with external documentation.

@Fast-Nop The practical solution is *exactly* as little documentation as is required. Nothing more.

Sure, in an ideal world we'd have heaps of documentation saying the same thing in every place you could think to look for it, with tons of examples, links to business metrics etc. and the whole lot would be kept updated. In reality that never happens - after the initial push to get all those docs out there, if there's way too much, then updating it is deemed a monumental but non-critical task - so it's just put off, often indefinitely. Or if it *is* done, then devs just update a few bits here or there, and bam, you have your inconsistencies & out of date bits all over the place too.

Of course, keeping docs concise doesn't prevent this nightmare scenario from happening - but it makes it a hell of a lot less likely. And when it does happen, if there's fewer docs to wade through, it makes it a hell of a lot easier to untangle the mess.

@AlmondSauce That's exactly why documentation is required in regulated domains where software actually matters so that people don't make an undocumented pile of crap out of the projects.

Also, if you don't document the rationals for the decisions, you are bound to repeat the errors that lead to the decisions in the first place.

I remember one of my first job interviews where the boss looked for some super coder, and it turned out it was because that there was no documentation except the code. The interview was pretty much over after I innocently asked him whether he had any plans to get to a more professional way of working. 😂

Depends on the amount of time you have:
Lots of time: Undercommenting is worse.
In a hurry: Overcommenting is worse.

I think the under comments are really bad

@Eklavya Both excessive and insufficient commenting can have detrimental effects on your code.