I'm pretty firmly in the "code as documentation" camp, what can I say? I think that most of the time, if you can describe an action with two or three words, you probably ought to be extracting that logic into a method by the same name.
IMHO comments are best used in a handful of situations, such as:
1) Marking hacks
2) Explaining unusual, non-obvious sections of code
3) Noting historical reasons for doing something in a non-obvious manner
4) Noting pitfalls to be avoided
5) Making passive aggressive remarks about the "business guy" who made you do something terrible
Not an exhaustive list of course, but I do think that it's best to think twice before writing a comment, asking yourself "how can I make this more obvious with my code?"
Comments
I'm pretty firmly in the "code as documentation" camp, what can I say? I think that most of the time, if you can describe an action with two or three words, you probably ought to be extracting that logic into a method by the same name.
IMHO comments are best used in a handful of situations, such as:
1) Marking hacks 2) Explaining unusual, non-obvious sections of code 3) Noting historical reasons for doing something in a non-obvious manner 4) Noting pitfalls to be avoided 5) Making passive aggressive remarks about the "business guy" who made you do something terrible
Not an exhaustive list of course, but I do think that it's best to think twice before writing a comment, asking yourself "how can I make this more obvious with my code?"