comments and regions
By Jeroen on Saturday 31 January 2009, 13:00 - Permalink
Let me put something straight right up front: I'm mostly against comments, XML documentation and regions in C# code. They might have their uses here and there, but most uses of comments/XML documentation/regions that I encounter just get in the way of what I really want to understand: the code. Most of the time, these things are no more than some bandage over a stinky mess of awfully written code.
I couldn't agree more with these guys:
- Sergio Pereira on XML comments
- Greg Duncan wrote a free Visual Studio add-in that eliminates the need to (ab)use regions for structuring your code
- Jeffrey Palermo argues that limiting code comments increases maintainability
These three aspects (XML documentation, plain comments and regions) are in most cases just an excuse for the guys coming after you: 'Hey, here's the code I'm giving you to maintain. It's full of crap and I don't want to take the effort to give you something well structured, but at least I added some comments to it, so you should be ok, right?'
I'm not saying that a good comment here and there can not be of use. Indeed, in some cases it's justified to explain WHY a certain approach was taken. But for the most part, your intent should be clear through the code structure, and wisely choices of class- and method names.
ok, rant over.