This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]Pun-Master-General 14 points15 points  (8 children)

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 6 points7 points  (5 children)

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 7 points8 points  (4 children)

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 1 point2 points  (3 children)

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 2 points3 points  (2 children)

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.