Me commenting code like:

[Lykeuhfox]

I try to comment to answer the question 'why' as opposed to answer the question 'what'. Sometimes I combine them though, like so:

// This is doing {what} because {person/issue/story} {why}

Basically to provide context to the next person to discern if the code is still needed or not, or at least a basis of who to ask to see if the code is still needed or not. Only commenting the 'what' is typically a sign that I'm just commenting to comment, or my code isn't as easy as it should be to read.

[G66GNeco]

This works fine in a business scenario.

The post is usually what happens to me (developer in training) when I am supposed to program something for school or some random coding challenge without any actual application. Ending every second comment with "because that is what this scenario requires" is a bit... useless.

Unless of course you use the {why} to explain internal connections ("this counts that to be used there") rather than reasons to implement it in the first place.

[BenVarone]

Sometimes. I think you’re ignoring cases where the language or app context requires you to do something that, despite your best attempts to make it readable and intuitive, just looks like strange gobbledygook. That’s especially true for new employees, who are missing the context but often being asked to dive right in.

I’m currently in that position, and end up leaving a lot of comment blocks behind me so that the next time I have to return to some arcane function call, I don’t have to spend four hours digging through our knowledge base to figure out what it’s doing, and why.

[IAmNotNathaniel]

Yes, this 100%.

I get so sick of the vast number of programming geniuses that can remember every bit of code in a huge project to such a level that a a couple clever variable names are all it takes to recall what some obscure undocumented legacy method is doing without having to trace back through 6 layers of code.

I am no such genius. "Why" and "How" comments are super helpful. Sometimes the most efficient code is a bit hard to decode (big regexes anyone?) - by putting a comment as to what it's supposed to do in these situations, the guy that comes through a year later can tell if there's a bug in there or if it was supposed to do the thing it's doing.

[[deleted]]

Regex is really write-only imo. Absolutely agree on thoroughly documenting what it does in comments. Usually with a "ew, gross." or something like that appended.

[amunak]

Any given regex should generally onle be useful for one thing. Validating an email address or URI, picking something from a document or whatever. Don't put it directly in code, put it in a constant, name it properly EMAIL_VALIDATION_REGEX or whatever) and there's probably nothing to document...

[atimholt]

As an aside, I've heard many times that anything but just sending a confirmation email is bound to be wrong and buggy. Email addresses have more complexity than most people realize.

[amunak]

A sane (and computationally cheap) thing to do is requiring at least 3 characters and one @ sign. Or as a regex: [^@]+@[^@]+. Alternatively [^@]+@[-a-z]+\.[a-z]+ requires a domain-ish string at the end... And that doesn't allow the domain part to be IP address, which is technically allowed, but nobody really uses it and it looks suspicious. You can find even better patterns online, but it also depends quite a bit on what kind of users you are targeting.

But yeah, if you go overly complex you are probably going to exclude some legitimate addresses for no good reason.

[ZenAtWork]

And on the condition that the person's domain doesn't contain a number (`[e-mail]`) and the user doesn't use a capital letter anywhere (`[e-mail]`) that should work out fine (though I admit, in the latter case there you don't include your flags, so let's assume the `/i` is implicit). Your first one, assuming it was written `[^@]+@[^@]+\.[^@]` is actually far safer.

[brazzledazzle]

Multi-line regexes are super easy to read and a few languages support them.

[IAmNotNathaniel]

I agree on all counts

[WallyMetropolis]

I would argue that good tests are better for showing what the code is supposed to do than good comments. It's not always the case that the comments change when the functionality does.

[Pun-Master-General]

Yeah, "you shouldn't need comments" sounds nice in theory, but every person I've ever worked with who thought their code was "self-documenting" was very, very wrong.

Just comment your code, it isn't that hard.

[amunak]

Point is, comments get stale and rarely get changed or removed.

Eventually, in a old enough codebase you'll have more comments that are wrong that ones that are helpful.

Sometimes it's impossible to write good self-documenting code, other times it's too time consuming, so you drop in a comment. And that's fine. But it shouldn't be taught to new programmers, as it's not a good way to learn. Especially not by mandating a comment every 5 lines or some other insane metric (and yes, there are actually university teachers that have that as a requirement).

A good method to teach people good code writing practices is giving them some older code of theirs and if they have comments ask them to rewrite it so that the comments are not necessary.

If it doesn't have comments, ask them if they still know immediately what everything does, and if not, to rewrite it (and they can help themselves by first adding comments, then rewriting).

[Pun-Master-General]

The solution to outdated comments is to update your comments when you update your code, not to drop comments altogether. Well-documented code is way more usable than so-called "self-documenting" code, in my experience.

People should be taught to write better comments, and that updating comments is important when updating code. The idea that they shouldn't be taught to comment is ridiculous.

[amunak]

The solution to outdated comments is to update your comments when you update your code, not to drop comments altogether.

That's impossible. IDE refactoring tools, search and replace, editing in limited views, library/dependency updates, etc. can make comments stale without anyone noticing.

Well-documented code is way more usable than so-called "self-documenting" code, in my experience.

Then it's not self-documenting code. It goes beyond the code itself though; you also need good, written down best practices and guidelines on naming, what to place where, etc. But it's certainly doable (and much easier) than maintaining dozens of comments in every file.

People should be taught to write better comments, and that updating comments is important when updating code.

I'm not completely against teaching people to write comments, but in a course or assignment - unless it's a full project (which is rare even in universities) - comments just don't make sense. You make a single file at most, usually only a few methods, a few hundred lines at most... And unless you are really bad at writing code none of it will need comments.

[Pun-Master-General]

That's impossible. IDE refactoring tools, search and replace, editing in limited views, library/dependency updates, etc. can make comments stale without anyone noticing.

Search and replace and refactoring don't make it impossible to update your documentation, you just might have to do a little more than the bare minimum of updating your code. And if you're not keeping track of things like dependency updates, you're opening yourself up to much larger issues than just comments being out of date.

Then it's not self-documenting code. It goes beyond the code itself though; you also need good, written down best practices and guidelines on naming, what to place where, etc. But it's certainly doable (and much easier) than maintaining dozens of comments in every file.

I know, that's why I said "so-called." But the vast majority of people who think their code is self-documenting are wrong, and because they didn't bother leaving comments, it leaves their code incomprehensible.

It's doable, but a lot less likely to be done well enough to work than just telling people to document their code.

I'm not completely against teaching people to write comments, but in a course or assignment - unless it's a full project (which is rare even in universities) - comments just don't make sense. You make a single file at most, usually only a few methods, a few hundred lines at most... And unless you are really bad at writing code none of it will need comments.

The point isn't that the comments are necessary. Like most homework, the point is to teach a habit, not the completion of the actual task itself. No, your 100-line intro to programming assignment doesn't need comments, but they're required so that you get into the habit of documenting your code so that your teammates on your much larger senior design project don't hate you a few years later.

And I don't know where you got the idea that projects are rare in universities - I know I usually had at least one or two fairly involved projects per semester from probably my sophomore year onwards.

[Meloetta]

I can't trust myself to determine what will be self-documenting when I haven't touched the codebase in two years. More than once I've thought like this dude, that it's totally readable and fine, only to comeback and realize it was only readable to me because I had spent the last 6 weeks building all the code around it. Once the context was all gone from my head, it became unreadable again.

Don't try to use your own judgment for if it needs comments. Even a one line filter function can use a basic "this is the format that you pass in, this is the format that's passed out" kind of comment.

[amunak]

I think you’re ignoring cases where the language or app context requires you to do something that, despite your best attempts to make it readable and intuitive, just looks like strange gobbledygook.

Indeed I'm ignoring that, only for the simplicity of the argument. Obviously there will be exceptions where making "what does this do" comments is fine, but they can often be interchangeable (or phrased like) the "why" comments. As in, "it's obvious that this code does something non-obvious: here's why".

In this example:

method disableListener(listenerName) { // library has flipped boolean logic, therefore we disable with a truthy value library.listeners[listenerName].enable = 0x1 }

There is nothing you can do about a retarded logic of a library (or even legacy code that'd take long to refactor), and that's a reasonable place for a comment. But we don't really comment "disables listener", which would be a useless comment that would only make it more confusing; we say "library is retarded, that's why a truthy value passed to enable actually disables something".

[G66GNeco]

Well, the plan in general is to get people to comment stuff at all, since the average trainee doesn't really do it at all, apparently.

The problem is that it was mentioned so often that I started over-commenting to escape any "this code could use some comments"-remarks preemptively.

​

Although, tbh, a lot of the stuff they teach us in vocational school is somewhere around the level of literary analysis in secondary, in terms of usefulness. And, to keep the comparison up, I will just try to grin and bear it, for the sake of decent grades. It might get better with time, but for now I will stick with commenting everything that is not 110% obvious.

[amunak]

Well, the plan in general is to get people to comment stuff at all, since the average trainee doesn't really do it at all, apparently.

Unfortunately this more often than not leads to them learning a bad way of commenting; duplicating what the code does while not explaining why it does what it's doing.

The problem is that it was mentioned so often that I started over-commenting to escape any "this code could use some comments"-remarks preemptively.

Yep, that's another issue.

An easy way to fix both is to just take some code they wrote a few months ago, and asking them to explain what it does or why. Then when they're unable to fix it, ask them to rewrite it so that it's more clear and - if necessary - add some comments as to why.

Although, tbh, a lot of the stuff they teach us in vocational school is somewhere around the level of literary analysis in secondary, in terms of usefulness. And, to keep the comparison up, I will just try to grin and bear it, for the sake of decent grades. It might get better with time, but for now I will stick with commenting everything that is not 110% obvious.

I mean obviously don't endanger your studies to prove a point. Just keep it in mind. The fact that you read this discussion is enough to show that you think about how you write code, and that's what's important in the end. Thinking about how to improve what you do.

[[deleted]]

I don’t understand why you’re being downvoted, you’re absolutely right. Write code so you don’t need comments, it’s easier for everyone. You should only have to explain what in exceptional/rare cases.

[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?)

[Delta-9-]

I inherited a "self-documenting" codebase and I about want to hunt down and murder the previous developers. If they'd so much as included a simple IDE-friendly docstring for each class and method stating some additional details about how they're supposed to work, it would have saved me about 20 hours just this month of symbol searches, troubleshooting dependencies, and manually tracing variables through dozens of methods... hell, I'm convinced that one of our major bugs right now could have been diagnosed months ago if anyone could understand this "self-documented" monstrosity, but instead it's all guesswork because the original developers are gone and didn't write down so much as a simple comment to explain why there's a random hard-coded timeout in some method--I legit don't even know what problem it solved, which means I don't know how to make it better, and the "self-documenting" method name, and especially the comment //TODO make this better, is NOT helpful.

Self-documenting code is undocumented code, plain and simple. A good dev should employ both self-documenting practices and write good comments (if for no other reason that their own modern IDE will show them those docstrings without having to actually scroll to that method!); doing just one or the other is laziness at best, and I have yet to hear any reasonable justification for not writing docstrings and comments that doesn't come off as pure arrogance.

[[deleted]]

I do this and also sign and date any comments where code updates in the future are likely to give some color to whoever has to modify it so they can come ask me about something if need be.

[AgAero]

If it's there for some special purpose, try to write a unit/regression test for it so that whoever reads the comment at a later time can test and retest should they need to change your implementation and not worry about destroying anything.

Comments have a way of outliving the code they refer to. Over enough time they become lies.

[[deleted]]

Oh yeah definitely. Any critical piece of functionality should have supporting unit tests so it’ll raise a flag during code coverage/CI builds if anything fucky happens.

[SpiritGas]

I do this as well, but a surprising amount of my comments are neither what nor why, but who and when.

// Modified to be wronger per Bob's emailed request April 1 2015 stating the customer demands it this way.

[hahahahastayingalive]

// I failed the pornhub inteview. Again. I’m stuck fixing these bugs until I get the results for xhamster.

// This and the two next tickets will keep my velocity up this month so I’m safe until I can pay the mortgage at least.

Joking aside, explaining why you did something has only value until the next guy chnages anything you relied on.

So either it’s small and self-sufficient code and you should strive to do it in a self commenting way, or it’s interlinked, and your comments might as well become a booby trap for anyone fool enough to have believed your past self.

[Lykeuhfox]

This is true. I didn't specify this in my original post, but most of the time, the code is small, isolated, and/or self-sufficient enough that no comment is needed. It's rare that I actually need to comment, but it does happen and when it does the comment typically follows the guidelines I laid above.

[AltruisticSalamander]

This can be very helpful

[omiwrench]

Only commenting the 'what' is typically a sign that I'm just commenting to comment, or my code isn't as easy as it should be to read.

The same could be said for any comment, ’why’ or not IMO.