I recently imposed on myself the constraint of coding without comments. Why?
- Comments rust faster than code, even when you’re careful
- Well written code can be read, and comments are annoying footnotes
- Comments make for lazy coding
Now, setting the bar at no comments at all seems a bit fanatic, but any value greater than zero is an invitation to using comments when better approaches are available, and like any addiction, I bet you can’t stop at one.
The Traditional View
In Programming C# 4, we write,
“…so even if your code is sufficiently clear that it’s easy to see what it does, it may not be at all clear why it does certain things….
We then go on to give an example,
Frobnicator.SetTarget(""); Frobnicator.SetTarget("Norfolk");
and then suggest that a comment will clarify the purpose of the code,
// Frobnicator 2.41 has a bug where it crashes occasionally if // we try to set the target to "Norfolk". Setting it to an empty // string first seems to work around the problem. Frobnicator.SetTarget(""); Frobnicator.SetTarget("Norfolk");
You can, however, eliminate these comments by being willing to put that information into the method name,
private void SetTargetToEmptyStringToWorkAroundBugInFrobnicator() { Frobnicator.SetTarget(""); } SetTargetToEmptyStringToWorkAroundBugInFrobnicator(); Frobnicator.SetTarget("Norfolk");
What I prefer here is that the code and comments cannot get out of sync, and if the bug goes away, I just remove the obviously redundant code. Since I started this approach I’ve not found the need for comments (nor the need for such absurdly long method names).
NB: I’m not advocating (yet), just experimenting.
Beware of the temptation to refactor,
When I first wrote this, I was tempted to factor out the common code:
private void SetStringToEmptyToFixBugThenSetStringYouWant( string newString) { Frobnicator.SetTarget(""); Frobnicator.SetTarget(newString); } SetStringToEmptyToFixBugThenSetStringYouWant("Norfolk");
While this has appeal, the problem is that when the bug is fixed, I’d have to change every call to this method everywhere, rather than just eliminating the call to the fix. Ugly.
Of course, I could add comments to explain why the code no longer makes sense:
The last thing you want is to end up with code like this!
// no longer need to set the empty string private void SetStringToEmptyToFixBugThenSetStringYouWant( string newString) { // Frobnicator.SetTarget(""); Frobnicator.SetTarget(newString); } SetStringToEmptyToFixBugThenSetStringYouWant("Norfolk");
Yikes!
42 Responses to Coding Without A Net