Jeremy D. Miller -- The Shade Tree Developer

Sponsors

The Lounge

News

Advertisement

Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at imagehelp@codebetter.com
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.


Posted 06-10-2007 3:18 PM by Jeremy D. Miller
Filed under:

[Advertisement]

Comments

FransBouma wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 4:06 PM

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

Common

Sense

Software

Engineering

;)

Jeremy D. Miller wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 4:09 PM

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 :(

Jay Flowers wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 4:22 PM

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.

Jay Flowers wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 4:28 PM

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?

Jeremy D. Miller wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 7:11 PM

@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.

Jay Flowers wrote re: Put Code Where You Would Expect to Find It
on 06-10-2007 8:45 PM

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.

Garry Shutler wrote re: Put Code Where You Would Expect to Find It
on 06-11-2007 4:59 AM

What about calling it the "Discovery" principle?

Jay Kimble wrote re: Put Code Where You Would Expect to Find It
on 06-11-2007 12:13 PM

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 <grin />.  

Jay

Jeremy D. Miller wrote re: Put Code Where You Would Expect to Find It
on 06-11-2007 12:43 PM

@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

jdn wrote re: Put Code Where You Would Expect to Find It
on 06-11-2007 1:17 PM

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?

Jeremy D. Miller wrote re: Put Code Where You Would Expect to Find It
on 06-11-2007 1:35 PM

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.

Mr_Real_World wrote re: Put Code Where You Would Expect to Find It
on 06-12-2007 8:43 PM

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?

Brian Sondergaard wrote re: Put Code Where You Would Expect to Find It
on 06-12-2007 10:17 PM

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

blog.softwarearchitecture.com2007/06/keeping-your-code-drawers-in-order.html">blog.softwarearchitecture.com/.../keeping-your-code-drawers-in-order.html

Brian

blog.softwarearchitecture.com

Jeremy D. Miller -- The Shade Tree Developer wrote Best of the Shade Tree Developer Part II
on 10-18-2007 9:20 AM

About a year ago I hit a patch where I wasn&#39;t able to blog much (something about finding a new job

Sam Gentile's Blog wrote New and Notable 170
on 12-02-2008 9:35 PM

Design Patterns/Software Design/Agile The Presenter First Pattern End to End, or, Another Run on the Hamster Wheel of Life Build your own CAB Part #8 - Assigning Responsibilities in a Model View Presenter Architecture Build your own CAB Part #9 - Domain

Add a Comment

(required)  
(optional)
(required)  
Remember Me?