I think of over commenting as harmful. Not only are you wasting time doing it, but it’s distracting when you looking at code.
I only comment for myself, stuff like FIXME and HACK and WTF and so on. I’m often told I should comment more, but mostly the one who tells me is someone who writes screen after screen of useless coments that I have to strip out to actually understand the code.
I like using method and parameter names that make their function obvious. If I have to comment a method just to generally explain what it does, it isn’t a well-written one.
Most of my comments are of the "Using 1-based indexing because of " (PreparedStatements Y U NO use 0 based indexing!?), "Starting iterator at i instead of 0 because of " and "Ending iterator at j instead of list.length because of ".
Of, if I’m doing something hackish that’s overly complicated for whatever reason, I try to explain what I am doing and how I think it should be done when I come back to it.
I have super strict formatting rules on myself:
public class MyClass {
public static final int OVER_9000 = 9001;
private int coolnessLevel = OVER_9000;
public void myMethod(int value) {
...;
}
}
if(...) {
...;
...;
}
else if(...)
...;
else {
...;
...;
}
try {
...
}
catch(Exception exc) {
exc.printStackTrace();
}
do {
...;
} while(...);
- ELSE, CATCH, and FINALLY, MUST BE ON THEIR OWN LINE OR YOU SHALL DIE
- There must be a space between parenthesis and curly braces.
- NEVER use curly braces for 1 line statements
- TABS, NEVER SPACES >:(
I never comment my code 
There, I fixed it for you! Har har.
Does anyone know why that convention/syntax is allowed/where it came from? I assume that there was a reason for there being this construct in so many languages, but for the life of me I can’t understand why they’d add this special case that seems there only to hinder readability/maintainability.
.> Sorry, this is one of my biggest syntax pet-peeves ever. It feels like giving a person a gun so that they can use to shoot themselves in the foot. xD
C, of course.
Oh yes, of course it did.
What about the why for it?
Why? C, of course. C is its own rationale now.
I see over-commenting as a signal that something is terribly wrong. Apparently your code is far from self-documenting.
Self documenting code is a myth. It presumes a vast amount of background context which most people won’t have. If you’re documenting code for the sake of yourself, that’s fine; but if you’re documenting it because you want other people to use it or work on it, I wouldn’t presume to think they know what’s in your head. Something as simple as:
double dist = dx *dx + dy * dy; // Get distance to gidrah
Why is it not a sqrt? Looks like a bug. You would probably leave an explanation of why you aren’t sqrting it if you were expecting someone else to take over maintenance of that algorithm.
Cas
That actually is a ‘bug’: the variable name is misleading and therefore requires a comment.
If you put that in to the context of how a mathematician describes formulae though you’d think even “dist” was too many characters. But still, even renaming it “distanceSquared”, you might be curious to know why it works with squared distances vs. real distances. Etc. I know it’s a bit of a straw man but there are lots of subtle variations on this.
Cas
Triggering curiosity beats confusion any time.
Self-documenting (low level) code ftw.
Die, comments, die.
Very true.
100% self documenting code is a myth, just like world peace is a myth. That doesn’t mean we shouldn’t strive to reach that goal.
WHY?!? Expand tabs to spaces >_<
As for curly braces, always on a new line. Partly because it’s what I’m used to reading and partly because my CS teacher would not accept programs written any other way -_-
EDIT:
Oh and, this
[quote=“Riven,post:53,topic:38743”]
Depends on how far you think it should go. I define self-documenting code as “code which you can read and understand”. Of course by just reading the code you are not going to magically understand the context of the problems it is solving and/or the process it is part of, unless the problems are really simple of course
But that kind of documentation you are not going to capture in code comments either.
Ha, now that I can relate to
Huh, take them here >:(
In all seriousness, I’m guilty of over-commenting code. I’m trying to scale it back. But one of my pet peeves is folks who use doc comment generators but don’t actually edit the generated comments, leaving you with fun stuff like this:
/**
* Gets the foo.
* @param name
* the name
* @return
* the foo
*/
public Foo getFoo(String name) {
...
}
Either do it right, or don’t do it at all!
/**
* Gets the foo.
* @param name
* the name
* @return
* the foo
*/
public Foo getFoo(String name) {
...
}
“You don’t say?”
Comments only work out when you’re making a lib.