Unlearn the concept that well-written code is also well-commented.
I don't have a problem with any technology or technique in use today enough to say that we should all unlearn it. But this habit of writing comments to document and explain our code is so deeply (and unjustifiably) embedded in our profession. My annual performance review questionnaire has a question: "Writes well-commented code" - "strongly agree", "agree", "neutral", etc. I have convinced my manager that the correct answer to this question is "N/A", but how many others have come to the same agreement?
I just opened a random file in one of the two IDEs that were open on my screen at the time of reading this question and it took me a less than a minute to find this:
/// <summary>
/// This method creates a foo depending on the bar name.
/// </summary>
public static Foo GetFoo( string barName ) {
...
}
Let's unlearn this.
Some reply is in order after 9 votes, 6 comments, and 18 votes seconding those comments.
I am protesting against the comment-favouring bias that we programmers have. I'm very concerned where, in the words of Robert Harvey, "erring on the side of more comments" may lead us.
Let's start with Greg.
- Why did Greg's employer hire non-programmers to do a programming job?
- If the job was to write a program in Perl, why give it to people "with only passing familiarity with Pascal?"
- If the intent was to hire people with a skill gap and train them (by taking Perl classes, lunch-and-learns, pairing with experienced Perl developers, frequent code reviews, etc.) so that they didn't have to write unconventional Perl code and write comment explaining the intent to senior Perl developers -- none of this training apparently took place. Why?
- And I am not making Greg's company solely responsible for the training; if these people signed up for the job, they made a commitment to learning a new skill, programming in Perl. Were they actually expected to act that way? If not, why? Did they understand that? If not, why?
You can see many problems in Greg's company right away, but Greg didn't say he'd kill to solve any of them. Before saying that, before probing root causes, we, programmers, are much more inclined to say, "if only this code had more/better comments..."
To Adam and @bigtang: I love good comments, too. The problem is, the vast majority of comments aren't good. There is lots of waste for every non-trivial piece of code with a good comment explaining the non-triviality. Adam, what if your business analyst needs to state those "unstated assumptions" and discuss them with a customer? Have your QA people talked to you about them? If you write a code comment about it and check it in and you are the only one of the four people (developer, QA, BA, customer) who has access to the source code, the chance is almost 100% the conversations will never happen.
We tend to see comments as assets, harmless in the worst case, and never as liabilities. Let's take a look at this thread. The original poster: "They're bulky and I'm always forgetting to update them. Do you [still] recommend using them?" The original poster is clearly concerned that they are a liability. But this opinion - "Use them as much as possible", it's so cool that they show up in IntelliSense - is a runaway favourite (60 upvotes).