Monday, July 7, 2008

Regional Vindication

Thank you, Jeff

I've long been an opponent of the over-use of regions in code in Microsoft's IDE.  It serves a unique purpose of hiding undesirable code, but it also serves the cost of hiding undesirable code.

So few developers know when to use this sort of uber-comment correctly.  I've always felt that comments, themselves, often serve as a cover for bad code.  I've actually seen regions used to separate out test functions by developer who implemented them.  I put a stop to that quickly in code review.

Distracted... I saw a spider coming down from the ceiling in front of the TV (watching The Big Bang Theory) and I did something messed.  I grabbed him by the web up high, and carried him at arms-length to the toilet where I flushed him into his new sanitary sewer home.

So, yes.  Regions.  From some unknown project in coding land.

bad regions

Seriously... how is that useful?  They even spent time counting the stars to line up properly in somebody's IDE.

I'd love to see the line numbers on that file.  I'm guessing that the "Properties" section has half a dozen public properties, 3 public fields, and a couple private members.  Constructor has one vestigial empty constructor.  Methods has 19 private functions, and 2 newly-public ones.  2 private variables are now public members.

My semi-educated guess here is actually not that far off.  The details are not important, but it points to a maintenance nightmare... not to mention readability.  Look at that code and tell me what it does.  You have exactly the name of the class to go by.  No comment on the class.... Why not a quick grep of the method names for help?

My modus operandi is to see a new code file and hit Ctrl-M,O.  This reduces the class down to its most basics:  the class name, its properties and the methods.  If all that doesn't fit on 2 pages of scrolling, your class is too big.  It does too much.  It's not one cohesive functional thingy.  If I can't describe it in an elevator pitch... or if it has, in the name something like "manager", "utilities", "common", "tasks"...  it's doing too much.  Regions are a poor-man's organization.

I believe, at this point, the languages facilitate a class definition that can be inferred from a glance.  Comments should compliment the code, not explain what should be clearly visible.  I'll get into, later, the use of comments externally, as well is within a function.

No comments: