programming and human factors
by Jeff Atwood
When you join a team, it's important to bend your preferences a little to accommodate the generally accepted coding practices of that team. Not everyone has to agree on every miniscule detail of the code, of course, but it's a good idea to dicuss it with your team and decide on overall approaches and philosophy beforehand. It promotes team harmony, and more than that, it's just common courtesy. As they say, when in Rome, do as the Romans do.
I've always been wary of cowboy coders who rolled into an ongoing project on fresh horses and immediately started dictating terms. It's a very short trip indeed from there to Who Wrote This Crap, and the predictable, inevitable finger-pointing at the foolhardy programmers who came before you begins. Don't be that guy or gal. Work with your team, not against it.
Still, there are some coding preferences people may feel.. strongly.. about. If that's the case, try to clear the air and address those strong preferences up front, as early as possible. Don't let them simmer. For me, the use of #region is one of those things. I tried to make myself clear in this twitter message:
So what is #region? It's a named hint you place in C# or VB.NET code to set a code folding point. Any code placed inside that region is, by default, collapsed when you re-open it in the editor. Here's a random example from the Log4Net project:
Immediately I have a problem: I can't see anything! I have to manually expand those sections to browse any of the code in this class. It is possible to configure the Visual Studio IDE to not fold any of the regions when files are opened, but this is the out of box behavior, so that's what most developers will see. And of course there are keyboard shortcuts to deal with the regions:
| Ctrl+M, Ctrl+M | Collapse or expand the block you're currently in. |
| Ctrl+M, Ctrl+O | Collapse all blocks in the file |
| Ctrl+M, Ctrl+L | Expand all blocks in the file |
| Ctrl+M, Ctrl+P | Stop outlining mode. (Ctrl+M, Ctrl+O resumes) |
Here's the really sick part: once you expand the above log4net code there's literally three pages worth of code there! After you strip out all the massive XMLDoc comments and the dozen or so #region directives, you could have had all the code at your fingertips with a minor flick of the mouse wheel, in a simple scrollable layout.
I daresay being able to see the damn code is more important than having it meticulously segmented into six pointless little named buckets, but apparently a lot of programmers can't get enough of stuffing their code into pointless little named buckets. It's as if they've forgotten what the scroll bar -- and incremental search -- is for.
The #region directive drives me bonkers. It's not evil, per se, but I feel it is criminally overused in practice and heavily prone to abuse. I strongly urge you to think about how you're using code folding, because as I see it, there are a lot of downsides:
#region has zero meaning to the compiler; it's a hint to the editor to allow code folding. It doesn't do any namespacing or scoping. Why, exactly, are we writing code to accommodate the editor? It boggles my mind that we'd add significant lines of code to our project that do nothing but offer organizational hints to the editor. Even traditional comments are a better value for your keystroke, because they can be more expressive. And folding is certainly no substitute at all for bona-fide refactoring.
I urge developers to write code that doesn't need folding to be readable, clear, and concise. I'm sure there are sane uses for code folding out there somewhere, but I rarely see them.
I like regions in the auto-generated code from some of the visual studio templates. Hiding all that crud is nice.
I'd never put them in my own code, and I remove them from it whenever I implement interface (it always sticks in a #Region - annoying).
#Regions don't kill code, coders kill code (if they've got a #Region)
Andy Burns on July 8, 2008 2:10 AMI also disagree. In team environments a consistent way of organising code makes things easier to navigate. It's not always about finding something, I would argue that more of the time it's about browsing through code that has been written by someone else - if you are familiar with the organisational structure of the code, its a great help.
Using regions is good practice.
Jimbo on July 8, 2008 2:39 AMThumbs down
Just use that hot key you mentioned to expand them all and pretend they're comments (they are comments!)
privatehuff on July 8, 2008 2:51 AMThis is ridiculous. How could clearly defining the elements that make up a class be bad? If every class that is written had regions for:
Private Members [or Fields, or whatever]
Constructors
Properties
Public Events
Private Events [think WinForms]
Public Functions [or Methods]
Private Functions [or Methods]
... then it's crystal clear where to find the code you are looking for. Someone reports a bug when they click Update in the customer screen of a web app or WinForm app? Well, go to the customer web page/form and look at the .Click event of the button in #region Private Events. There is a problem with saving the data of a customer to the database? Look for the .Save method in #region Public Functions. How could anyone not advocate a cleaner, logically laid-out code base, where ridiculous scrolling is not required?
HardCode on July 8, 2008 2:52 AM@Silvercode:
We've gone down that route before, and it makes changes more difficult.
There's nothing easier then simply putting the code exactly where everyone would look for it first.
We have pre-programmed regex searches that look by client name and those serve perfectly if we have to know if a particular client has a particular hack turned on at a moment's notice (like on a conference call).
Complicating a long series of very simple lines of code is not an improvement.
Rick Scott on July 8, 2008 2:55 AMIf you're constantly editing one small area of a giant file, why isn't the part that changes frequently in a *different* file?
That's stupid. Tha'd be like if you're constantly retouching your car's breaks, you should move the breaks to the back seat for easier access.
Regions are -like many tools- an excellent service the VS provides that could be overused, misused or well used.
Banning Regions just because you don't know how to properly use them is foolish Jeff. You contradict yourself so many times… you don't want visual bloat but you prefer to have a file opened in front of you with xxxxx lines of this is not the code you are looking for.
Grouping things in a reasonable way is because our brains do not have the power of the IDE to just jump back and forth of the code. Regions help us to hide things and group stuff.
I group all the Delegates/Events, Public properties, etc. Because I know when I open the file, what I'm looking for. I just expand the part I want to see. and search from there. Less scrolling.
Also VS2005 CRAWLS when the file is converted from 2003 and was a big form where there's lots of Interface Designer code. So having Designer code collapsed really makes the file usable again.
Martin Marconcini on July 8, 2008 2:58 AMI agree. In a team environment where you're working on code not written by you, you're usually more interested in how the code of the class interacts, not whether it's a public instance method or a private static method.
An example as a maintainer: the first time I look at a class, I know I'm looking for something that sets Foo = Bar. I don't know whether it's a public instance method or not, this information is just noise. I'm interested in WHAT THE CLASS IS DOING, not whether the programmer chose to pass a 'this' pointer to a method or not.
#region folding hinders maintenance for people not familiar with the code.
STeven on July 8, 2008 3:09 AMOne thing this post has surprised me with is how many people apparently seem to be using alternative editors (such as Vim or Emacs) to write C# code.
(Don't want to start a One True Editor Holy War here - I'm just surprised that Unixy editors are so popular on an essentially Windowsy language)
Graham Stewart on July 8, 2008 3:18 AMI agree it's a religious choice, but I do find some good uses for a #region (I'm still working on VS2005):
- In a WinForm, a #region is handy to collapse all the declaration of UserControls (as well as the InitializeComponents)
- Again, in WinForms, wrapping the Event Handlers in a #region is a good idea, since they never contain the real code for that Event, which is usually written in a separate method (to be used from different events, with different EventArgs)
I use #region a lot, it helps me organize the code overrides/implementations for the different base/interfaces of my classes.
But, to be honest, I've found a big negative point for #region: when many programmers write on the same classes, they do not share their mind patterns, and sometimes methods switch from a region to another with no apparent reason, new methods appear in a region they shouldn't be in, etc.
My solution: I check all the code and decide where to place the regions, then I make sure I'm the last one to check-in all the files :-P
heh, once when I was contracting I saw the best ever use of regions.
A 10,000 line method, broken up by regions. :O
My eyes still bleed to this day!
@Mark: from Graham Stewart post The worst thing that I saw in your post was cases..
Huh?? You might want to practise your code review skills!
There is a public method in the private methods region.
A private method in the public method region.
Folding the nasty region makes it look like Hackers get FileNotFound.
Folding the Irrelevant logic makes it look like result is true.
And I think I'll carry on using switch/case statements in my code. :)
I strongly disagree with Jeff: I find code folding very easy for the same reason why I don't use a completely expanded tree inside the Explorer.
In my opinion Explorer sub-trees are collapsed to get a better overview and to find more easily the thing you're looking for. That's exactly why I use the #region directive.
NickB on July 8, 2008 4:05 AMLate to the party and didn't read all the comments but still...
I don't get all these negative comments. Especially those that say other IDE's (eclipse?) do it automatically. That means you are using the tool wrong.
tasks for your IDE (in some tree for example or whatever):
- Group members by public/private
- ordering members on name
- mark your constructors
- fold each function separately (if you really want to do that)
- separate list of properties and functions
- ...
that is all technical.
But good luck letting your IDE group functions based on businness logic. It just can't.
Regions also will not make those decisions for you. So the hard work is still yours (yes it can get complicated it larger projects). But at least now you have something to work with.
I agree. Its not nice to have a method folding ability when it folds the method and comments separately leaving you 2 folded things instead of 1 (the method with comments). I bet Visual Studio makers did method folding the easy way and didn't allow wiser folding, because wiser folding would have been so much harder to be implemented.
Silvercode on July 8, 2008 5:01 AMicremental search does not work unless you want to keep remembering the name of every method, class etc.
Yes, god forbid we actually remember the names of the routines and variables we use..
@wenke this is awesome!
http://img184.imageshack.us/img184/8929/72ve0ptu4iry6.jpg
Some final points as the discussion winds down:
1) I personally find the way Visual Studio handles default folding to be completely unsatisfactory bordering on useless. It is entirely possible other editors (Vim, Emacs, Eclipse) handle this in a more rational way. I agree that lots of optional folding can and should be done exclusively by the editor.
2) Folding doesn't kill code, Programmers kill code. Yes, it *is* possible to use folding in a rational, sensible, restrained way. It is a pity that I almost never see it used that way in the Visual Studio ecosystem, though. It's typically what you see pictured in the blog post.
Jeff Atwood on July 8, 2008 5:05 AMHeh, I think I'm beginning to get the smackdown model, some interesting comments have emerged here.
I've used regions in moderation in the past with some success, though I could take or leave it. As usual though, my opinions suffer from never having to have maintained a large project.
One place I used to use regions all the time was for properties, to wrap up the boilerplate getter and setter code. Fortunately that problem has largely been solved with automatic properties (and hopefully we'll see automatic backing variables in the next version of C#).
Several people have expressed a disbelief that you need to manually specify regions for code folding. The truth of the matter is that VS does quite a bit of automatic folding, though not to the granularity of most other editors. You can fold using directives, namespaces, comments (including XML comments), classes and methods (I might have missed some) but not things like conditionals and loops. Personally I've never had a need to fold at the level of individual conditionals and loops (if you do, it probably needs to be refactored) but I can't see it would be something terrible difficult to add to the IDE and it most likely has already been considered, so I wonder why it hasn't.
I hate it when you implement the interface in Visual studio and it auto-adds regions around the generated code. And when you add the interface and click it again, you get yet another region. Bad.
You can turn that off in Options-Text Editor-[Language]-Advanced-Advanced. I do think it's the wrong default though.
Errr... I use regions in the VB.NET Express IDE and it does *NOT* automatically fold them closed every time I open up a file.
I think it may remember them in the user options file of the project, which tends not to be distributed or source controlled.
So Jeff, do you use XMLDoc comments? I've used them for a library I wrote that I thought might end up being public and I hate them. They clutter up the code so much. Do you think it's bad form to stick with standard comments for internal projects where you don't really need a help document?
I find XMLDoc comments incredibly useful, even for internal/personal projects. Remember if your using Intellisense the XMLDoc comments come up in the tooltips which, if you've not touched the project in a while can be extremely useful in remembering what a particular method does or one of it's bizarre edge cases. You can collapse up XMLDoc comments, though annoyingly there isn't an option to collapse them all at once.
If the code would fold with one click to give you a nice clean definition, that would perhaps make it worthwhile. But it doesn't. Particularly if you have regions within your class.
Forgive me if I misunderstood but you can collapse to definitions (Context Menu-Outlining-Collapse to Definitions). It doesn't show just the public interface (Object Browser is good for that) but it makes it easier to see. Of course it doesn't play well with regions, as someone else pointed out.
This is analogous to menus, treeviews, toolbars, etc in UI design. You can use these organizational tools to make things easier to use and find, or you can create a mess.
Of course, Jeff has stated that he hates trees too ;)
[ICR] on July 8, 2008 5:13 AMWow, loads of comments.
I had to admit to being old school and not being a big fan of code folding. If you're working through somebody else's code then it breaks the flow of the code. I know it's hidden in plain sight but that's how it works for me.
To be honest a lot of the more complex code I've seen which is packed regions and comments and everything else could have been done with a lot simipler code.
Greig Harper on July 8, 2008 5:14 AMThe presence of massive XMLDoc comments bothers me as well. It's necessary, but it gets in the way so often.
Not really, you can put XML docs in a separate file and include them. Here's an example: http://www.codeplex.com/thehelpertrinity/SourceControl/FileView.aspx?itemId=2259changeSetId=7821 (scroll down to the members).
What's necessary is a tool that manages all this for us, built right into VS. It's something I've wanted to write for a long time, but just never got around to it.
Kent on July 8, 2008 5:46 AMGot a bunch of boring boilerplate code that makes your eyes water? A slew of ugly, gnarly code that nobody in their right mind wants to look at? Long, horrible spaghetti code blocks?
Perhaps you're doing the dirty job of maintaining someone's legacy code which looks like the afore-mentioned. In that case, it might be useful to close the code into regions that you can get out of your sight once you checked and double-checked them: Here's that ugly hack from 20 years ago, I just made sure it has no side-effects on what I'm doing, so let's get those 500 lines out of the way so I don't have to scroll all the time.
Sure beats rowing the mouse wheel. Or imagine control-effing in vi! :)
Nikola Gedelovski on July 8, 2008 6:09 AMI also disagree with the article.
Ivan on July 8, 2008 6:20 AMWith great power comes great responsibility. Like any language feature that can be misused (partial classes, delegates), some common sense needs to be applied. If a developer hasn't the sense to see that overuse of such a feature will cause readability maintenance issues then you've got bigger problems within your team than you originally thought.
Andy on July 8, 2008 6:27 AMIn defense of regions, when you are doing code reviews or presentations, I find it helpful to use regions to focus your audience's attention on one set of code at a time.
On CodeProject there is a set of macros that automatically adds regions and comments around procedures (ctrl-d), and opens/collapses all regions (ctrl-shift - / +). It's one easy route to go if you like regions as I do.
(Alt-ctrl-j) in R# is an awesome way to add regions as well...
I don't think it's a code smell, because regions are soooo easily opened through VS or macros... And you are using resharper to develop right? It's really a crime not to, as those light bulbs R# provides can really be helpful for tightening code (and regions certainly doesn't hide those errors or suggestions - though a pragma will).
Just my $0.02,
Wow. The asininity of some of these comments is astounding. Code folding hides things and groups things, yes, BUT THAT'S WHAT CLASSES ARE FOR. What Jeff is saying is that if your classes are so long that you need to fold them, YOU SHOULD REFACTOR THEM TO BE SMALLER. Need to group business logic? Pull that shit out into a separate class. That's what I meant by code smell - if you're tempted to use #regions, consider whether you should be creating a new class.
I understand that sometimes you're stuck with legacy code, but try to take some time to refactor that shit first, if at all possible. At the very least, put your new logic in a new class and call it from the old code. Anything else just exacerbates the problem.
John on July 8, 2008 6:59 AMI disagree. I think the author was using regions for the wrong reasons. On a scenario where multiple guys are working on the same file , this is a perfect way to ring fence your code. Working with just your region code expanded gives you the feel of working on a small chunk of code and savesyou from un necessary scrolling/searches.
Sree on July 8, 2008 7:13 AM@post :
I strongly disagree. The ability to hide regions of code in order to underline others is a good thing. And Visual Studio can be configured to show them open by default AFAIK.
Andrei Rinea on July 8, 2008 7:21 AMTwo points. The argument that regions are all most developers will ever see because it's the default seems nuts to me. It seems utterly reasonable to expect a professional coder to set the preferences of Visual Studio. They are programmers. It's one thing to expect non-technical users to accept program defaults because they don't know enough to go set preferences. That's a poor excuse when it comes to professional programmers. Secondly, regions are not code written to accomodate the editor; they're written to accomodate the coder. Overall, this seems like a fairly shallow complaint. Set your editor the way you want things to look and get over what other people prefer in their editors.
Spitzen on July 8, 2008 7:29 AMSometimes I am forced to work in Centura/SQLWindows. I am told it was popular outside the states sometime in the 90's.
By default everything is folded and I mean everything. Every if, for, else, function, variable blocks.. That and the editor is not very discoverable, so while there probably is a un-colapse all hotkey I haven't found it yet.
It can be the most annoying feature ever if not implemented properly.
On the other hand, Netbeans collapses my code in a lot more friendly manner and finding the collapse all un-collapse all hotkeys was discoverable from the menu.
gruckiii on July 8, 2008 7:32 AM Emacs is getting a lot of attention in this post. I think it's
because it was the first IDE (or one of the first),
It isn't just that. Emacs over the years has had support added for pretty much every text editing need a person could possibly have. That's a *lot* of functionality.
Nobody who sets out to create an editor from scratch (not even Microsoft) can possibly produce all that functionality when they are done. So the absolute best any other editor can shoot for is implementing a subset of Emacs. Some parts of that subset they may manage to implement a bit better, but it will still just be a subset.
Its true that occasionally these alternate editors do something new. However, any new functionality someone may come up with can just as easily be added to Emacs. If its useful, it will be done by someone. If its really useful, it will get moved into the default codebase.
So there's really not much point in anyone ever creating their own editor. I'm not upset that some people still have the hubris to do it, as the competition ends up making Emacs better. But that's all it is doing.
T.E.D. on July 8, 2008 7:32 AMYour project is now full of crappy code that you can't see
I want to have this framed and put on the wall at work :-)
Will you settle for a motivational poster: http://img184.imageshack.us/img184/8929/72ve0ptu4iry6.jpg
wenke on July 8, 2008 7:37 AMwtf. i thought it was standard behavior to fold code *automatically*. #regions seem to be some ugly hack. indentation and curly braces should give editor enough hinting to fold if requested by user. don't see how it fits to teamwork, as it should be editor-side feature only. if i recall correctly, even vim handles code folding quite sanely, without any special #regions or other crap. code folding also allows you to have clear overview of a class or other code.
zokier on July 8, 2008 7:46 AMThe underlying problem with using #region for anything other than what it was designed for (hiding auto-generated boilerplate) is that it is not in any way understood or checked by the compiler.
So whatever scheme you have can't ever be relied upon when you actually need to read the code to find a bug, drill down on one particular area. Put your public methods in the 'private region', your event handlers in the stubs region, the compiler won't care. Put your 'customer99-specific' code in a function or class, and you can be sure a change to it does not change the behaviour for customer-74. A region, all bets are off.
If your code is bug-free and perfect this is not a problem. But the more 'real-world', pragmatic, rushed and buggy your code is, the bigger a problem you have.
Jeff, yes!!! vim probably other editors too have very very advanced folding / marking / navigating features. That stuff in your post is rediculous.
Ian on July 8, 2008 8:14 AMfor vim you have folding by complex expression based on the language, by indent, by other things, and those expressions are already made for basically every programming language out there, no one should be manually marking fold locations in code.
Ian on July 8, 2008 8:18 AMAgreed. Regions are not anything I've personally found interesting or useful. I'm constantly stripping them out of generated code.
Mike on July 8, 2008 8:25 AMVisual Studio does automatically fold pieces of code. Functions and block level.
Regions just allow you to declare custom fold points with names.
So please people, don't think Visual Studio doesn't do other code folding that doesn't require Regions, because it does.
I do not agree. I see your points, and I acknowledge them, but my personal experience is that folding (with vim) improves my productivity.
Indeed, I take care of adding folding tags as much as I can, because I prefer to keep control of the folding level. I do not like having to unfold every indentation, that makes code navigation very hard. I do like having folding at the routine level. It makes my navigation and my cut-and-paste very easy. If I want to delve into the details of a routine, then I unfold it with a single hit of spacebar.
I think it's a matter of taste, but to me, folding increases productivity so much that I install vim 7, if I don't find it on the system, just for folding.
#region Important Stuff
_foldingIsGood = true;
_jeffAtWoodIsWrong = true;
#endregion
@Keith try something like:
#region Private Methods
public WtfEnum AreRegionsBad()
{
WtfEnum result = WtfEnum .No;
switch (coderType)
{
case SensiblePro:
result WtfEnum.No;
break;
case Hacker:
#region nasty
result = WtfEnum .Yes;
break;
case Noob:
#endregion
result = WtfEnum .FileNotFound;
break;
}
return result;
}
#endregion
#region Public methods
private bool FoldingGoodButRegionsOpenToAbuseAndMistakes()
{
bool result = true;
#region Irrelevant logic
result = false;
#endregion
return result;
}
#endregion
I haven't noticed if it's been said, but VS has plenty of automatic code folding features, WITHOUT using regions. Regions allow further, more programmer defined folds to be created.
VS even let's you use code folding on other file types like HTML, XML, etc... (uh oh, here comes the XML debate again)
HB on July 8, 2008 9:30 AMI use regions to prevent my boss from touching code that he doesn't understand. If he actually opens that code, then his head will explode, and, headless, he will start breaking the code in subtle ways that take days to unravel.
So my regions normally look like this:
' This region contains all the drawing code for this control.
' Do not edit this code unless you take the time to understand it.
' WARNING: This code is very complicated.
' Small changes may have effects that are not immediately visible.
#Region Drawing and GUI Code - Do Not Touch!
...
#End Region
This usually keeps our code safe ... usually.
I also use regions to hide lists of private variables and public properties.
Evan on July 8, 2008 9:40 AMJeff,
I wholeheartedly disagree with you. Between this and your preference for ...
if (someString == )
over
if (someString == string.Empty)
... I'm beginning to have my doubts on your content.
from Graham Stewart post
The worst thing that I saw in your post was cases. Using cases inside of classes can cause BIG problems in VB when integrating with certain visual objects. Honestly I have no idea if this is true in C# or not, being that My C experience is in C++.
Sorry Jeff, you are wrong on this one, but not for all the reasons above.
In my world, we receive massive XML (and custom) data files from other companies. We don't dictate the format/schema, and only rarely can we convince them to change it from whatever absurd raw format they wanted to send us in the first place.
Imagine a health-care-related XML file with ~500 data elements logically grouped like this:
physician
lname
fname
group
address1
address1
city
state
zip
specialty
taxid
healthplanid
upin
ac
phone
faxac
fax
/physician
hospital
similar data to physician
/hospital
patient
similar data to physician
/patient
etc. These are manually loaded using C# because address1 can be blank for the physician but not the patient, whereas the zipext can be blank for anyone but the hospital. Also, each individual element has its own rules for different companies, different error messages that must be shown, and about 5 years worth of custom, client-specific enhancemen...err, hacks to get around random stuff they send to us.
With code folding, we can group hundreds of lines of code like this:
[-]#region physician
// CrazyClient42 can send us data without a physician lname tag
// CrazyClient18 can send us an empty or lname tag
xnTemp = IncomingXmlDocument.SelectSingleNode(//Root/physician/@lname);
if(xnTemp == null client != CrazyClient42)
throw new exception(Missing Physician Last Name);
if(string.IsNullOrEmpty(xnTemp.value) client != CrazyClient18)
throw new exception(Empty Physician Last Name);
PhysicianDataStructure.lname = xnTemp.value.trim();
... repeat for every data element in physician...
#endregion
[+][#region hospital]
[+][#region patient]
If there is a problem with the XML file loading, we need to stop immediately and halt the process with the appropriate message. Using these regions has saved us countless minutes looking through hundreds of lines of similar-looking code.
Can you put these in their own functions instead of regions? I guess you could...you could even put them in their own files if you wanted to. You could put them in their own DLLs! But why? They really are all part of the same function: loading a given XML document, baby-sitting it every step of the way because you have to and storing the orderly data in a set of known programming structures.
I've always wished for a way, when browsing a class, to hide private methods/fields of that class. So I like #regions.
Ultimately though I'm in the format the crap out of it camp. We've been coding in plain text for too long. I want an IDE/language that treats code as a database, and lets me view functions, apply my own (not checked in!) tags, formatting, and organization. I want to be able to use rich formatting to, say, paste pictures in as comments. But most of all, I want to use the blink tag IN CODE. :)
Mason on July 8, 2008 12:11 PMI think it's useful to be able to organize code using regions. I want to hide stuff I'm not working with, scrolling up and down becomes tedious and icremental search does not work unless you want to keep remembering the name of every method, class etc.
Patrick on July 8, 2008 12:50 PMDoes anyone who dismisses regions as an excuse to hide crap code or avoid refactoring actually work in the real world? I'd love to spend time refactoring some of the poorly designed projects i've had to work on but I can't because I have a steady stream of new jobs coming in which might actually help the company I work for turn over a profit. I can picture the conversation with my boss now.
Sorry boss, can I delay starting on project x for a couple of days, i'd like to do some work on project y
Why, whats wrong with it?
Well, nothing really, but the some of the classes could do with refactoring...
Anyone care to guess what the answer will be? I'm always re-assessing and where necessary trying to refactor my work but it's something I have to fit into time between projects or in those rare instances where I find myself at a loose end.
There are a couple of people where I work who are the sort of people who get wound up about coding preferences and the like and blog about this sort of crap, who are coincidentally the least productive programmers we have.
In any case, joining a project and refusing to adopt any conventions that the other developer(s) may have taken time to use is plain arrogant. I hate hungarian notation, 'm_' variable prefixes etc but i'll use them if it's consistent with the project i'm working on. Likewise, I expect other developers to show my projects the same courtesy.
Rick Mather on July 8, 2008 1:07 PMThis is why I prefer editors like Vim (GVim for you Windows people).
I can control whether folds exists, how deep they go, where they start and stop and much more.
@Rick Scott: You could create some more elaborate way of doing things, like encapsulating search logic and exceptional situations, use object oriented programming and inheritance etc. That way there would be actual structures instead of hack regions.
When I design and program software, I can see all objects in my mind. So lets say I want to access the logic of CrazyCustomer33. I would know that it is in a subclass of parse logic eg. in ParseLogicCC33. So I just open that class instead of starting to search through hundreds or sometimes thousands of lines of code.
Silvercode on July 8, 2008 1:51 PMIt seems the #region was your first wife that left you for you bset friend.
Couldn't you find 50 more reasons why not to use #regions?
#regions is a great thing. Period.
Charlie on July 9, 2008 2:04 AMfolding is simply natural for c#. could not say that for c/c++ or f# or any other from top to bottom language.
Danijel Kecman on July 9, 2008 3:10 AMGod bless you, Jeff! Would that every programmer in the world would read your blog and put your words into practice!
Aaron on July 9, 2008 3:52 AMi like code folding. when working with long code, it is very handy (to me, at least) to be able to just fold up the parts that i dont need to look at. Even when folded, search will still find stuff in folded code..
i'd much rather open a piece of source and see the fold comments denoting the different sections. This (in my opinion) is not only a form of documentation but also a high level organization tool. Even more so in team environments.
It sounds almost like the writer of this article is one of the 'cowboy coders' that they complain about at the top..
That's just my 2 cents..
scott on July 9, 2008 5:33 AM@I daresay being able to see the damn code is more important than having it meticulously segmented into six pointless little named buckets, but apparently a lot of programmers can't get enough of stuffing their code into pointless little named buckets. It's as if they've forgotten what the scroll bar -- and incremental search -- is for.
NO! Use #regions to aid model-driven software development, and use #regions to separate true concerns that can't be identified by a tool, because you've yet to set-up an explicit open-closed interface.
Actually, Eclipse has this option also (fold methods and inner classes) without any #region thing, and I find it very useful when navigating the code base searching for bugs. It also helps me from getting my self into trouble. I mean it, if you're doing some task and while rolling down the code you find some stupid comment, you laugh and break your concentration. Or even worse, you find stupid code and by the time you get to add your stuff, you're actually thinking: Who made that crap? or Maybe I can apply some Spartan programming there and there goes your zone.
Good article thought, you've got to keep up with your opinions
I think #regions is a personal preference, some people like to see all the code they have, even though it's 10,000 lines. Some people like to hide the contents of methods/functions they have written when they are done with it. I'm with the latter group.
When I'm done with a function, I hide the content of the function, leaving the function name and comment intact. The comment + function name should be enough to easily work out what the function does. If it's not, you are a messy coder. There really shouldn't be a need to see the content of a function when you are done with it.
http://img234.imageshack.us/img234/8783/picture3xe9.png -- how I usually do it
Thomas Winsnes on July 9, 2008 8:40 AMcriminally overused in practice and heavily prone to abuse: Absolutely yes. 100%.
Show the meat. Hide the fluff if it really helps, but *please* don't hide things to rote.
One-size-fits-all approaches always end up hiding what you really care about. And if your class is so big you need to organise it 'like chapters in a book' then for your own sake refactor it.
[Today's smackdown seems to have struck a nerve, yes?]
piers7 on July 9, 2008 9:40 AMI love regions. If I'm writing something long and winded, I can put pieces in separate regions and find them easier.
#region Structures
...put all my structures here
#endregion Structures
Let's say I have a page of structures. I can fold this and I don't have to look at them. When I look at my file, I see what I want to see. If I want it all, I do CTRL-L.
Just FYI.
I always name both sides of my region. Also, if you want to find the other end of a region, put the cursor on #region and hit CTRL-]. This works for squiggly-brackets too.
Visual Studio.
have to respectfully disagree.
#region puts good use of code grouping, where I put the methods in relative segments (like private and public attributes). This grouping also enables me to navigate to the method I'm interested in faster.
Althrough, it's given that the regions need to be properly named in order for this to work.
Andy on July 9, 2008 11:03 AMTo think the IDE should be responsible for grouping (with #region) Constants, Properties, Constructors, etc, together also assumes that all programmers organize their code in the same manner. I think people start forgetting that the way we use our IDE isn't the same as the next guy.
Not everyone is going to organize their code in a way that can be predicted by the IDE. Regions seem to be a rational, flexible way to allow people to organize (or not) their code aside from the automatic folding already done.
HB on July 9, 2008 11:13 AMYea, I hate it too, nothing like coming up with another way to hide something that should not be hidden...
Mac on July 9, 2008 11:36 AMJeff I love your stuff, but of all the lines to draw in the sand on coding practices, in my book this ain't one of them. The mere presence of a region reflects at the very least an attempt at code organization, and that is not a bad thing.
Brian H on July 9, 2008 12:23 PMWhoa, good to hear that someone as well respected as Jeff also can get all the same crap about regions I received on my blog post: http://blog.codedemora.com/2008/02/29/just-say-no-to-c-regions.aspx
Saul on July 9, 2008 1:11 PMAnd I don't have to use regexp searches to find things. I just open the class ParseLogicCC33, because I know they the logic is there.
How everyone could know that the logic is in ParseLogicCC33 instead of being in a region? Well, you have a design of the solution. It should have a class diagram. This is the right way of doing things anyway. You design first, then implement. Everyone who has to touch the code should first look at the design, because otherwise its more like guessing or figuring out on your own or with your coworker.
So you have the design and a class diagram and its easy to take a glimpse of that and see where all the logic is. After that no more regexp searches.
Surely hacks work if done right, but I don't like the idea that most stuff is made by weird hacks that are called solutions that everyone understands when there is even no design documents. One thing leads to another and soon the whole system is full of undocumented hacks.
If regions are used, there should at least be programming conventions for them.
Silvercode on July 9, 2008 1:16 PMOverused #regions suck. That's why some people (self included) hate them.
They're fine when they hide visual noise. They suck when they hide information.
Joe Chung on July 9, 2008 1:32 PMEvery time I read a post on this blog and the comments associated with it, I am reminded again how lucky I am to not have to code with Windows anymore. 3 years ago, I switched off Windows + Windows programming after ~12 years doing it for money. Since then, every time I'm exposed to Windows coding, I'm sort of shocked like wow, they keep falling farther and farther behind.
I don't mean this as a holier-than-thou comment at all. But honestly, I feel very fortunate that I don't have to deal with any of this stuff. MSFT elected to create a keyword for code folding? Really, when free IDEs do it automatically?
And the platform + tools are still encouraging people to minimize the number of source files they have, like it's 1990? It makes sense that if Windows can't efficiently handle lots of files, then you want all your code in a single file. But wow, I had no idea it was still this bad.
I know everyone can't switch off Windows and still keep the bills paid, but I'm glad I have been able to. Good luck to you guys.
RG on July 10, 2008 2:13 AMA provocative idea, and after thinking about it, I partially agree. If regions are used to mask dirty code you are ashamed of, then you shouldn't use regions. You should refactor.
On the other hand, I find regions useful in illustrating what the class is about. I tend to use lots of private helper methods: these are prime candidates to go to a region. Don't expand the region, and you have the high-level view of what the class is about, without clutter. Expand the region, and you can go into the nitty-gritty of the implementation.
That being said, partial classes are an interesting alternative to regions. If you want to isolate a specific group of behaviors, put it in its own partial class.
I disagree with you on this one. Kudos to you on making your point though. I certainly don't have to agree for the point to be valid. Anyhow, like anything else regions can be used poorly and that is a shame.
jride on July 10, 2008 3:09 AM@RG
Rather than sounding holier-than-thou as you put it, how about trying to sound intelligent or at the very least informed before commenting? It's been stated multiple times already that code folding is integrated into the IDE and that regions are optional.
HB on July 10, 2008 3:34 AMMy take on the subject.
http://morten.lyhr.dk/2008/07/visual-studio-regions-are-code-smell.html
Morten Lyhr on July 10, 2008 4:49 AMWeak post. Regions are fine. Anything used excessively is a pain...
Chico on July 10, 2008 5:55 AMI concur wholeheartedly.
#Regions are just one more M$ attempt at dumbing down the software community. Okay maybe that's a bit paranoid of me and someone actually thought they would be beneficial, but still. My IDE should help me, like say, trusty ole R2-D2. It should not baby me like Dr. Spock.
Mattkins on July 10, 2008 7:22 AMRegions are a lazy trick to allow some organization. IMHO the future is in storing everything in binary intermediate language that doesn't lose anything but always runs rather than is such a fragile thing as a text file. eg. Think Spore procedural creatures stored in .png where the image is the sum of the parts in the creature. You see IDA Pro disassembler and latest movie production software doing something along there lines.
The IDE, language and the result to need become much, much closer together so when you are programming you are editing and seeing the end result - immediately! Think of creating levels in a game editor built into the game engine or painter painting. The moment you write the code and hit, if it's ok, it takes effect and is immediately in the latest version of the binary. Version control, testing, specification etc is built into the system of course to kill problems errors before they get anywhere.
zzz on July 10, 2008 9:48 AMCode Folding: The first IDE feature necessitated by a bad object declaration design.
NickHodges on July 10, 2008 11:36 AMC# Regions are a CodeSmell
There is a second use of Regions - hiding portions of a method. To any agile developer, this would immediately tell you that the method is too long. But I see the practice time after time. So much that I wrote about Regions as a CodeSmell.
a href=http://aspadvice.com/blogs/rbirkby/archive/2008/05/12/Code-Smells-in-C_2300_.aspxhttp://aspadvice.com/blogs/rbirkby/archive/2008/05/12/Code-Smells-in-C_2300_.aspx/a">http://aspadvice.com/blogs/rbirkby/archive/2008/05/12/Code-Smells-in-C_2300_.aspx/a">http://aspadvice.com/blogs/rbirkby/archive/2008/05/12/Code-Smells-in-C_2300_.aspxhttp://aspadvice.com/blogs/rbirkby/archive/2008/05/12/Code-Smells-in-C_2300_.aspx/a
RichB on July 10, 2008 12:29 PMI like regions too, but at the same time I don't like them. Maybe its like using goto. Its handy, but not recommendable. So people use regions until it is taken away from IDE:s. Period. But is regions really as bad as goto? Well, it depends. If you are not capable of living without regions, you will not see why you shouldn't be using them and you think everything is just fine.
So I said that I also like regions. Would I use them? In some projects many classes are so big that I would use regions for the sake of clarity, unless I would have time to refactor the classes. Also I might first add regions, because that way I would see what parts need further refactoring and redesign.
But here I see again that thinking programming hits and designing is left back somewhere. So there needs to be more effort put into actually designing and modeling the program so less regions will be needed.
Silvercode on July 10, 2008 1:42 PMRegions are great. Sometimes when you're working with awful APIs you can't avoid excessively long code where often there's no need to overfragment the code into unneeded functions and files.
I agree with some of your points, but i have the same opinion of comments. I hate how unreadable comments make the code.
Bobby on July 11, 2008 6:37 AMI use them for code that shouldn't be run, due to a change in requirements but may have to run again soon due to the requirements reverting back. I wish people could make their minds up :p
Mr. Tidey on July 11, 2008 9:17 AMYou should write a post about the evils of classes. Who wants their code hidden in a separate class? Someone with something to hide is who. If you are a truly excellent coder you'll throw information hiding to the wind and just put everything out there in one place. How am I supposed to see it if someone organizes it into manageable sections?
Publius on July 11, 2008 10:11 AMI have two words for you: Baby and Bathwater.
Among other things, you seem to imply that once code is placed inside a region it is no longer accessible! No, you can't SEE it, but even if it were expanded, you probably wouldn't bother LOOKING at it unless you thought that's where a problem was. And the region will automatically expand while in debug mode, so it isn't like the environment is HIDING anything from you. So why not get it out of the way when you KNOW you don't need it?
When you clean your house and put things into your closet, you can organize things neatly or shove the things in there with no thought. But should closets be done away with just because some people use them to hide junk? Should organized people have to forgo their use so that messier people will be required to leave their slop sitting out for the world to see?
Anything has the potential to be abused. Regions are no exception, but I code more quickly by using them without any of the detriment you decry...and I'm sure I am far from the only one.
Mr. Scott on July 11, 2008 1:47 PMhi,
I agree and disagree...
http://blogs.msdn.com/nilotpal/archive/2008/07/11/is-code-folding-that-bad.aspx
Nilotpal on July 12, 2008 4:49 AMPersonally, I like regions... I agree that there are occasions when knowing which region to open when looking for a method is a pain. However, there are:
1. SEARCHES
a. Ctrl+Shift+F - Find across project / solution files
b. Ctrl+I- Incremental
c. Ctrl+F - find within file
2. The method-name / property drop-down list at the top of each code tab
3. GOTO DEFINITION
4. FIND ALL REFERENCES
In fact, the number of times I find myself looking in a file just to browse it is so minimal it can be discounted. I am just about always looking for soem reference that one of the searches above has found.
I also consider regions (when used 'how I like to use them' big grin to have a useful side-effect - it makes me think about the intended audience of the code, and how it will be used. If it's public, I need to consider the caller and interface considerations etc - perhaps CLR interop is a consideration etc., but if its private perhaps I can pass around different types, etc. The region can be a marker to remind us to think about these things.
However, having said all that, where I currently work regions were historically used as an ALTERNATIVE to methods / functions even (you know, the two-thousand line method with twenty regions in) - which I can assure you I do consider to be total and utter misuse of regions :(
Nij
Nij on July 12, 2008 5:36 AMI have to agree and disagree. I personally love to use regions to organize my code according to implementation until I started to use the custom tool used for generating a plugin template for our project which totally abused the use of regions. A region was created for each object declaration (method, fields, properties, namespace, etc...) in the IDE. That is totally sick.. i'd have to unfold multiple times for a 'public bool foo = false'??
Anyway.. same with most here, regions, if used properly is undeniably good.
Stynx on July 13, 2008 5:47 AMEric Gunnerson, one of the MSFT engineers who was involved with C# development for a long time, agrees:
http://blogs.msdn.com/ericgu/archive/2008/07/10/region-sliced-bread-or-sliced-worms.aspx
Len Holgate calls it #herebedragons
http://www.lenholgate.com/archives/000400.html
Jeff Atwood on July 13, 2008 6:07 AMI personally like regions for breaking code files into groups of members by construct type (like chapters in a book) and went so far as to create a tool to automate doing so. NArrange will group members into regions and can also apply sorting by name, accessibility, etc.
http://narrange.sourceforge.net
However, I realize there are many downsides to regions and that not all teams condone their usage. Thus, the most recent version of the tool allows you to apply grouping and sorting of members without region directives. See Daniel Root's post for more info:
http://blog.lifecycle-solutions.com/NArrange++Take+2.aspx
Also, for those just looking to strip regions out of code, this may be helpful:
http://www.codeproject.com/KB/codegen/narrange.aspx?msg=2579903#xx2579903xx
James Nies on July 13, 2008 11:24 AMJeff, I'm totally with you.
Reading through all the comments I can't believe how many developers think that #region is OK. It's (almost) always a substitute for good factoring, and definitely a code smell.
This was my post on the subject a few weeks ago:
http://stuartharris4.blogspot.com/2008/06/c-regions-inline-comments-and-blank.html
folding in general looks like a weak version of literate programming. Which, given your opinion of folding, you'd really hate.
Shawn on July 14, 2008 5:10 AMDisagree.
Visual organization goes a long way in my book, and code folding is another tool for doing so. The folded sections give me an overview of the groups of methods (public, private, events, interface impls, etc.) in the module. When I open a code module, I first hit Ctrl-M-O to collapse all regions, scroll to the region I'm interested in, then Ctrl-M-M to expand that region. I can then browse all methods in that region by signature. Additionally, I organize my methods alphabetically by region, so finding a method is even faster.
I'm definitely a fan of code folding and relish the relief from page after page after page of code when I have an idea of what I'm looking for. If I know exactly what I'm looking for, I use the search tool, but otherwise I'm a browser-navigator when it comes to code.
Craig Boland on July 14, 2008 9:29 AMThe #region directive is useful when you write big classes: controls or web service classes. In case of these, splitting them in smaller ones would lenghten and/or complicate your code. In classes which are shorter than 2 pages the use of the #region directive is silly.
Jeno on July 15, 2008 9:20 AMI have to disagree.
When inheriting legacy code in +1000 lines, and no logic ordering. That's a headache.
I must agree though, VS 2003 does not expand regions properly and can be a pain at times.
That said, I would rather see the outlining logic before jumping straight into any programming.
Bywin on July 17, 2008 2:07 AMa good developer can adapt to any working environment:
http://www.dotmad.net/2008/07/good-team-developers-are-cameleons.html
100 years ago, some physicians said it was impossible for an object more weighted than air to fly. They were SURE it was impossible. Today, we just smile...
When can we you be sure about the right direction of progress? I mean: Regions really can't fly? Are you absolutely sure? Block diagrams also hide information; however, they can fly. Are regions like elephants trying to reach the sky by waving thear ears?
Whatever will be, will be.
Thanks for shaking our neurons, Jeff
oscar on July 21, 2008 6:56 AMI use them, I like them.
No, I don't use it to hide anything, just to give myself a cleaner working surface to work on. I'll typically place public methods in one, private in others, if applicable event handlers in a different one and so on and so forth (precisely as in the sample code shown).
If I am working on redefining a class' public interface, I may not want to have all the private methods get in the way when I scroll through.
You want to use incremental search... sure... but what if I don't know what the heck I am looking for?
I think the point you are making has some validity to it as it relates to the tangential points you make (bloat, maybe separation of concerns somewhere in there, etc), but come on... but you have to admit it is highly religious, as in you were high on a horse and had some adrenaline flowing when you wrote this...
Not all opinions are truths, nor all of those absolute. regions have their place, here and there and some people certainly abuse and misuse them, but as much as any other tool they all step in to aid the smith feel more comfortable in the exercise of his trade.
I like them, I don't *love* them or swear by them, but I certainly don't mark them with the scarlet letter like you have done here.
Guillermo on July 22, 2008 11:26 AMHi,
After a zillion comments, no-one is probably going to read this one. But I happen to agree with Jeff here. I hate the regions because I can't see the code and so can't as easily browse it and get a feeling for it.
(And for seeing an higher level view of the code (which is what most people seem to do with folding), I mostly use a plugin called ModelMaker code explorer, it shows the structure of the class in a separate tree next to my code.)
Wow.
It seems to me that since you ventured out on your new project and the cash might not be flowing as easily as it was before you've just been picking the most religious subjects and getting on your soap box about them. If you need the page rank up so that you can get more click throughs that badly Jeff I'm sure someone can sub you $10 til pay day.
It's starting to border on drivel, it really is.
Carl on July 25, 2008 5:53 AMOne more helpful hint, specifically for those who are forced to work on a team enamored of regions (this is cobbled together from a couple of sources online):
Sub CollapseToDefinitionsButExpandAllRegions()
DTE.ExecuteCommand(Edit.CollapsetoDefinitions)
DTE.SuppressUI = True
Dim objSelection As TextSelection = DTE.ActiveDocument.Selection
objSelection.StartOfDocument()
Do While objSelection.FindText(#region, vsFindOptions.vsFindOptionsMatchInHiddenText)
Loop
objSelection.StartOfDocument()
DTE.SuppressUI = False
End Sub
Instead of setting Alt-Left to CollapseToDefinitions, you can set Alt-Left to this macro, which will CollapseToDefinitions, then expand all the regions. You get your nicely collapsed code...but now you can *see* it. The annoying regions will still be there, but at least now they won't get in your way as much when you're trying to work.
Enjoy!
Kyralessa on July 25, 2008 12:30 PMI have to agree for the most part with what you're saying about Code Folding, I hate it and it seems a deceptive practice.
However recently I have been folding one specific section of my programs, the import sections. I normally have roughly 20-30 lines or more of simple import commands, which my IDE (Netbeans) handles automatically
Simon on July 28, 2008 10:36 AMJeff! Yes, finally, someone with common sense. I _AGREE_ WITH YOU.
Regions are to be banned. Even good coders get tempted, while bad coders, of course, litter their code with it.
I actually propose to #region out the coders who use #region. Inside a nice (dark of course) cube section. The problem would be that with all the regions they would use, they wouldn't see their desk, their chair and their lamp... Who cares, they can't see their code.
Max
Max on August 5, 2008 11:18 AMI have to say I agree with Jeff on this one. When I first discovered #region, I thought 'oooh, cool feature', but I soon discovered all the deficiencies he talks about. So I moved on to more productive activities.
But I did find one use for them. Delving into the intricacies of - wait for it - Windows .INF files, specifically TEXTMODE.INF, which you will find on your Windows setup CD, and which is thousands of lines of impenetrable crap. But (and here is the saving grace) it is broken up, somewhat at any rate, into sections, so what I did was pre-process the file with an AWK script and insert #region directives around each section. I could then use the Visual Studio editor as a kind of outlining tool. It helped me a lot, and maybe this post will help someone else out there one day.
Paul Sanders
www.alpinesoft.co.uk
I have to say I agree with Jeff on this one. When I first discovered #region, I thought 'oooh, cool feature', but I soon discovered all the deficiencies he talks about. So I moved on to more productive activities.
But I did find one use for them. Delving into the intricacies of - wait for it - Windows .INF files, specifically TEXTMODE.INF, which you will find on your Windows setup CD, and which is thousands of lines of impenetrable crap. But (and here is the saving grace) it is broken up, somewhat at any rate, into sections, so what I did was pre-process the file with an AWK script and insert #region directives around each section. I could then use the Visual Studio editor as a kind of outlining tool. It helped me a lot, and maybe this post will help someone else out there one day.
Paul Sanders
http://www.alpinesoft.co.uk
Which do you prefer?
public void Init()
{
initA();
...
initZ();
}
public void Init()
{
#region initA
#endregion
...
#region initZ
#endregion
}
The comments to this entry are closed.
Subscribe in a reader
Subscribe via email
|
|
Traffic Stats |
