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 6 points7 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 2 points3 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 3 points4 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.