Sponsored By Aspose - File Format APIs for .NET

Aspose are the market leader of .NET APIs for file business formats – natively work with DOCX, XLSX, PPT, PDF, MSG, MPP, images formats and many more!

Put Code Where You Would Expect to Find It

 

I’m going to propose a new design concept with an admittedly awkward name called the “Put Code Where You’d Expect to Find It” Principle.  It means exactly what it sounds like.  A team should strive to consistently put different types of code into separate, logical places in the structure.  Following this principle, I’m going to put security related code in a namespace with “Security” or “Authorization” or “Authentication” in its name.  Data access code is going in “Data” or “Persistence” namespaces.  Business logic is going to be placed in the appropriate Domain Model class, or an accurately named Use Case Controller (if you swing that way) or Service Layer class.  The point being, assuming a modicum of familiarity with a system, that you should be able to consistently and quickly find any piece of code by its functionality.  Think of this principle as creating a Dewey Decimal system for your code. 

Part of the “…Where You Expect to Find It” principle is to simply create and enforce some consistency within your system.  On several of my Agile projects I’ve noticed “this is how we’re going to do it” moments when the team settles on a pattern to follow, then follows it.  “We’re going to do data access with a repository class for each parent domain class object” or “I like this pattern, let’s use it for all web pages” or “let’s suffix all of our Gateway classes with Gateway” are all examples.  When these patterns are defined and applied consistently, it becomes easier to find the code you’re looking for.  Defining, and refining, these patterns of a system seems to lead to big jumps in developer throughput and increases a team’s ability to exercise collective code ownership. 

I think the main reason to be excited about Ruby on Rails (RoR) and its ilk is improved software maintainability through Opinionated Software.  RoR forces web developers into a bit of a straight jacket, but that’s a good thing in a way.  RoR enforces a consistent source code tree layout; a consistent division of responsibilities between model, view, and controller classes; and consistency in naming conventions for just about everything.  While some of the design choices or limitations of RoR may be debatable, the advantages for maintainability are undeniable.  Any experienced RoR developer is going to be able to quickly understand the patterns of a new RoR application because the “this is the way we do it” decisions have been made as a community and baked into the framework itself.  RoR puts code where you’d expect to find it.  My colleague also suggested Jakarta Commons as another example of consistency.  I’m still a little dubious about some of the details, but I’m starting to get much more interested in Software Factories as well for the consistency that they create.

Moving to a negative example, last year my team was extending our legacy web application and needed to find the code that governed the navigation bar at the top of each page.  We finally found the code smack dab in the middle of a huge code file called “Security.asp” in the “_ScriptLibrary” system folder created by the old Visual Interdev tool.  To make matters worse, we found three different versions of “Security.asp” scattered through the code tree.  At this point we expect to find everything and the kitchen sink in the “Security.asp” file, but it was a terrible place to dump the navigation code.  One, the name “Security.asp” doesn’t imply navigation logic, and two, a system folder is an unusual place for custom code.  The application could be improved by simply moving the navigation subroutines into a separate “NavigationLibrary.asp” script in a logical folder.  Then the people who come behind us will be able to find the navigation logic when we’re gone.

The newer Integrated Development Environment tools help quite a bit with this.  I wouldn’t want to live without ReSharper’s CTRL-N shortcut to find any class in the solution (with wild cards too!).  Then again, finding code with ReSharper will be a whole lot easier if you employ good naming practices and put code where you would expect to find it.

About Jeremy Miller

Jeremy is the Chief Software Architect at Dovetail Software, the coolest ISV in Austin. Jeremy began his IT career writing "Shadow IT" applications to automate his engineering documentation, then wandered into software development because it looked like more fun. Jeremy is the author of the open source StructureMap tool for Dependency Injection with .Net, StoryTeller for supercharged acceptance testing in .Net, and one of the principal developers behind FubuMVC. Jeremy's thoughts on all things software can be found at The Shade Tree Developer at http://codebetter.com/jeremymiller.
This entry was posted in Maintainability. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://blog.softwarearchitecture.com Brian Sondergaard

    Jeremy, I like the way you’re thinking. This sort of discipline has a direct impact on developer productivity and produces immediate return on investment.

    I picked up on your thoughts and provided what I think is a pretty good example in the J2EE space. Check it out at
    http://blog.softwarearchitecture.com/2007/06/keeping-your-code-drawers-in-order.html

    Brian
    http://blog.softwarearchitecture.com/

  • Mr_Real_World

    What you describe is all to common when as a consultant you constantly move from job site to job site.

    In fact, TTM (The Total Mess) is sort of the standard you’ll see because very few companies want to spend to money or time to write software correctly.

    Most of the time you have some point-headed CFO type screaming at the CIO who will then force the development team to cut corners, who after enough “crap” from their managers will just TTM it and go home for the day.

    In corp America most dev’s as sent to the management track after 3-5 years anyway. Seldon if ever will you find a programmer who knows how to do anything but TTM.

    In fact, the CFO and CIO reward the TTM.

    Twisted huh?

  • http://codebetter.com/blogs/jeremy.miller Jeremy D. Miller

    jdn,

    I think Jay is objecting to seeing Javascript embedded within C#/VB.Net code somewhere besides the code behind. From experience, that’s painful beyond belief to troubleshoot and change.

    If you need to codegen or use a template to build your Javascript, that’s not too bad, but keep that stuff out of the Controller’s in something like you’re suggesting.

    Then again, life will be much easier if you can quickly run and verify the Javascript without having to fire up an ASP.Net page.

  • http://www.e-Crescendo.com jdn

    I’m not quite sure why having something like MyNamespace.Web.Common.Javascript would always be a bad thing. If you have some common need across pages, wouldn’t it belong in a common class?

  • http://codebetter.com/blogs/jeremy.miller Jeremy D. Miller

    @Jay

    I’m in a WinForms frontend and Java backend world actually.

    I know exactly what you mean. It used to piss me off to no end to inherit systems that wrote HTML and Javascript snippets in VB6 components.

    Think on this one though, a former colleague related a story to me one time of a team that built a dynamic website by building all the HTML output in PL/SQL stored procedures. Top that!

    I actually wrote this post last year at my previous employer. Their main ASP.Net system has a single class nicknamed the “Borg” that is or contains:

    * The Application Controller
    * Navigation controls
    * HTML construction
    * Data access
    * Generates Javascript
    * Transaction management

  • http://www.codebetter.com/blogs/jay.kimble Jay Kimble

    Jeremy,

    I thought you were talking about something else from the name.

    I have run into my share of “systems” where the actual code was hidden through some layer of indirection. One common thing that we all use (that I really hate and do my best to avoid) is where one write JavaScript code within a class… not a Page’s CodeBehind mind you, but some class in the system. It might be in a Library project where the Page is passed to the class doing the work or it could be somewhere else… it really sucks when one comes later and has to figure this garbage out…

    Anyway, I’m tlaking ASP.NET and I know that you use RoR, so you probably have no idea what I’m talking about .

    Jay

  • Garry Shutler

    What about calling it the “Discovery” principle?

  • http://jayflowers.com Jay Flowers

    So we are in agreement. I used the word disciple and you used the words knowledge, experience, and diligence.

    I still want to know what things we can do to make it easier for developers to do the right thing. Please don’t read into that sentence that the answer has to be a tool.

    You said: “What is design but the accumulation of a lot of little decisions?” Sure the tools mentioned help cut down on re-inventing of the wheel. I don’t think that we have done as much as we should to cut down on re-invention of the wheel.

    Is education a part of the answer? Sure it is, and I realize that takes time.

  • http://codebetter.com/blogs/jeremy.miller Jeremy D. Miller

    @Jay,

    What is design but the accumulation of a lot of little decisions? Yes, things like Software Factories, Opinionated Software, and frameworks can help developers “fall into the pit of success,” but I don’t think you get great results unless the “right thing” is socialized and internalized by the developers themselves.

    It’s knowledge, experience, and diligence first, tools second.

  • http://jayflowers.com Jay Flowers

    If I understand you correctly you are talking about using discipline to continue what RoR, Jakarta Commons, or CI Factory would lay down? They work at more of a macro level and your desire to to extend this into a finer grain layer?
    I like Robert Martin’s use of the term viscosity in this kind of situation. How can this be done in a way that makes it easy for developers to do the right thing. How can they be enabled to know what the right thing is to do?

  • http://jayflowers.com Jay Flowers

    Hmm,
    Common sense, in this context, is the ability to easily grasp the value in a given practice.

    Unfortunately this does often translate into common practice.

  • http://codebetter.com/blogs/jeremy.miller Jeremy D. Miller

    Possibly, but I gave it a name that sounded cool in my own head :-)

    But unfortunately, I’d have to debate you on the “common” part :(

  • FransBouma

    Isn’t this all part of the already very widely known CSSE methodolgy?

    Common
    Sense
    Software
    Engineering

    😉