Contributing - Regions

Topics: Feature Requests and Contributions
Jun 1, 2011 at 3:00 PM

A discussion starter - as opposed to a direct question:

I was having a look at the source code yesterday, and the most prominent standout bit is the large use of regions in the codebase?  Is there a technical reason for this that I'm missing.  I guess I don't find much value in a region that wraps a single 3 line method. It also hurts my Macbook's 13" screen. :)

Cheers
Ray 

Coordinator
Jun 1, 2011 at 5:28 PM
Edited Jun 1, 2011 at 5:36 PM

Hi Ray,

The primary purpose of these regions is organization; they keep the locations of members predictable and consistent throughout all of my code files.  The secondary purpose is to make it easy to quickly collapse away parts of the code that are not needed while analyzing and debugging.

Don't forget to use Collapse to Definitions (Ctrl+M+O) and Toggle All Outlining (Ctrl+M+L). In particular, I use Ctrl+M+O quite often. I tend to use it immediately as soon as I open any large document for which I need to locate a particular member.  I also use it during debugging sessions to focus the editor on the members being analyzed.

If you don't like the regions, then simply expand all members using Ctrl+M+L as soon as you open any file.

I've been using these specific regions throughout my code for years.  I have found that most people that use regions aren't consistent with them, or they choose very strange combinations of regions, which I suspect is why regions have gotten a bad rep.  But mine are very well thought out and I use them consistently.  They should make the code much easier to browse and understand once you get used to them.

Basically, the organization of every code file is as follows:

  • Public state
  • Internal (actual) state
  • Constructors
  • Methods (behaviors)
  • Event handlers
  • Nested types

To create the regions for new classes, use the layout snippet within an empty class definition. You'll find the snippet in the solution under the Build\Snippets\ folder. For more information about this snippet and the purpose of the individual regions, read my blog post.

- Dave

Jun 1, 2011 at 5:55 PM
Hi Dave

I fully understand the rationale for using regions, it just seemed to fall into the excessive use category. I guess it's just a religious debate over whether they provide value or not. I just find that if your class is so big to justify the use of regions, it's probably too big. :)

Cheers
Ray



On 1 Jun 2011, at 18:29, davedev <notifications@codeplex.com> wrote:

From: davedev

Hi Ray,

The primary purpose of these regions is organization; they keep the locations of members predictable and consistent throughout all of my code files. The secondary purpose is to make it easy to quickly collapse away parts of the code that are not needed while analyzing and debugging.

Don't forget to use Collapse to Definitions (Ctrl+M+O) and Toggle All Outlining (Ctrl+M+L). In particular, I use Ctrl+M+O quite often. I tend to use it immediately as soon as I open any large document for which I need to locate a particular member. I also use it during debugging sessions to focus the editor on the members being analyzed.

If you don't like the regions, then simply expand all members using Ctrl+M+L as soon as you open any file.

I've been using these specific regions throughout my code for years. I have found that most people that use regions aren't consistent with them, or they choose very strange combinations of regions, which I suspect is why regions have gotten a bad rep. But mine are very well thought out and I use them consistently. They should make the code much easier to browse and understand once you get used to them.

Basically, the organization of every code file is as follows:

  • Public state
  • Internal state
  • Constructors
  • Methods
  • Event handlers
  • Nested types

To create the regions for new classes, use the layout snippet within an empty class definition. You'll find the snippet in the solution under the Build\Snippets\ folder. For more information about this snippet and the purpose of the individual regions, read my blog post.

- Dave

Jun 1, 2011 at 5:57 PM
Oh, and great work on the library. Looking forward to the new stuff. :)


>
Coordinator
Jun 1, 2011 at 6:17 PM

Hi Ray,

I appreciate your feedback, thanks.  I've been diligently working on the next release for the past few weeks to include Rx Parsers.  I believe that James is also working on some new extensions as well.  Hopefully we'll have something to deploy this week.

> I just find that if your class is so big to justify the use of regions, it's probably too big. :)

I see your point, but I didn't use file size to justify the use of my regions :)

Guidance and consistency are the most important factors here.  Secondary to those, being able to collapse the regions even in regular-sized files (as opposed to "big" files) while analyzing or debugging code is invaluable.  I've seen developers use some very strange organizations even in very small files, and debugging experience becomes just as strange when many small files use completely different organizations and provide no ability to collapse even small sections away during analysis.

I agree though that the value of regions is subjective in some ways.  Some devs prefer to have absolutely no organization in their files and they use the drop-down lists at the top of the code editor window to navigate their code, while I avoid the drop-downs completely.  Others prefer to have some well-known organization and have it checked with StyleCop, and perhaps they don't care to be able to collapse sections to make editing and analyzing the files easier, while for me it's imperative.

- Dave

Coordinator
Jun 1, 2011 at 9:42 PM

It would be nice if we had a structured editor ;)

http://blogs.msdn.com/b/kirillosenkov/default.aspx?PageIndex=3

This way regions / organistion (how you view the code) would just be a user preference :)

My 2 cents....

Personally I don't use regoins. Normally the team I'm working in will standardise the way we organise our classes. I guess being an open source project it's harder to do that.

Coordinator
Jun 1, 2011 at 10:43 PM
Edited Jun 1, 2011 at 10:46 PM

Hey James,

(This never fails to be a hot topic ;)

A structured editor is certainly an interesting idea; however, file organization is often semantic.  I would only want to use a forced structure for my regions and not, for example, to order the methods within a Methods region.  I like to choose the order of members within the regions based on what makes sense.  Although I do typically follow the same patterns, sometimes I'll change the order of members within a region if I think it will be easier to understand or debug.

Essentially, my layout snippet is quite simple to use and it affords us the freedoms that we need to organize files semantically within each region.

Many times I've considered writing a VS add-on that would automatically organize the file into my preferred regions (perhaps also customizable for StyleCop users, etc.), but I've always decided against it because the layout snippet is just so easy to use and I fear the auto-layout would be too restrictive and confusing.  Its only real benefit would be to enforce that all devs use the correct layout, but in a controlled project (such as Rxx) we don't have to accept any code that doesn't meet our formatting requirements.

I'd love if StyleCop's existing rules were flexible enough to enforce the ordering of my regions, but unfortunately they are not.  The default StyleCop rules around ordering are a bit strange, especially the ones about accessibility, readonly fields and static fields.  That's why I've disabled them.  They are a burden without any value; e.g., do you really care that static methods appear before instance methods?  Does it really make them easier to find or the code easier to understand?  I used to think so, until I started mixing static members with non-static members a few years back and not once have I noticed any related issues finding members or understanding code.  That said, I still try to put static members above others, but there are times where the "staticness" of a method is simply added as a performance enhancement (indicated by FxCop), yet the location of the method is still meaningful because it's located immediately under its only caller.  (Sorry, this is a bit off-topic now ;)

> Normally the team I'm working in will standardize the way we organize our classes

I have standardized the way classes have been organized, that's a primary goal of the layout snippet. :)

Furthermore, the regions provide guidance for devs to follow the standards; otherwise, without regions, the standards are less likely to be followed due to differences of opinion and forgetfulness.  In my experience as a lead dev, developers will not organize files correctly unless they have something to guide them: the layout snippet.  (And yet still I've found most devs not caring about organization at all and not even applying my layout snippet.  So much for the title of "lead dev" ;)

And don't forget, one of the most useful features of regions is their ability to collapse.  I use this feature often while reviewing code and debugging.

I do think the usefulness of regions is subjective to a degree, but if you see the value in a structured layout, and you see the value in StyleCop rules to enforce structure, then surely you can see the value in an explicit layout snippet - even excluding the ability to collapse entire code blocks.

- Dave

Coordinator
Jun 1, 2011 at 11:00 PM

FYI - There is an addin that puts everything in regions. I think it's called "Regionate". I spend most my time in reflector & linqpad though ;)

http://www.rauchy.net/regionerate/