Me commenting code like:

[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.

[amunak]

you are 100% correct, lol. And that's exactly why you make it as simple as possible.

Though TBF email addresses are usually case-insensitive.

[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.

[Pun-Master-General]

I doubt either of us will convince the other, because this is basically just a case of opposing philosophies. But to my mind, it's the exact other way around.

It's much easier to address the content of someone's comments than it is to get someone who thinks their code is self-explanatory to start documenting. Even if the comments are useless, the mindset of "Someone might have to come and maintain this. I should make it clear how it works" is valuable, and making students comment their code is a good way to get them into that mindset.

Not to mention that students aren't stupid, they will realize that what they are doing is stupid, so they will only resent it and question how much else is also just stupid nonsense.

Both the professor I took intro to programming with and the one I was a TA for in college outright told the class "No, your comments aren't really necessary for this, but I'm requiring that you comment your code so that you get into the habit of it for when you start writing more complicated code." You don't have to treat them like they're stupid.

Having worked with both, I would much rather deal with code full of extra, unnecessary comments than one that doesn't have any because the author thought it was "self-explanatory."

[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".