Reflections on software development . . .

First Steps to Quality Code

Joseph Reddy — Mon, 24 Aug 2009 09:13:35 -0500

This is a reply to a comment on a previous page that for technical reasons got posted as a new entry as opposed to a comment reply.

Comment:
Your articles are of great inspiration, Thanks Reddy.
Am a 2.5 yrs old Software Engineer and worked on Maintenance Projects.
Could you please suggest me a route towards Quality Software Engineering and better growth pattern?

Reply:

Being that this is an article dedicated to reading books, I might suggest the apparent…read. And I don’t mean read books on new languages or technologies like Share Point or the newest version of the Apache server. Though these technical books have their place, they do little to advance your comfort level with building quality applications.

It all starts with the code you type. If an application has a poor design or weak architecture it can still have high-quality code. If you are not sure the design you have chosen is the best, the design can be more easily understood and changed as necessary if its code base is solid. To that end I highly recommend that both Code Complete and Writing Solid Code are read and discussed. (Note that Writing Solid Code refers to the C language, but it requires no knowledge of C to understand what the book is teaching.)

Beyond this I think it is imperative that you continue reading about the way other developers write software, finding a style and method of your own that blends the best of what you find. Books like The Pragmatic Programmer, Domain Driven Design, Refactoring, Object-Oriented Analysis and Design with Applications, and any of the Agile programming books give you insight into how applications are approached by other developers. I would hope any developer reading these books would find good ideas that fit with what they do and how they think. I would also hope there is plenty to disagree with in these books, as no one size fits all.

I often argue that no aspect of software development is more important than communication. Whether it is how the code communicates to the next guy who has to understand and update the code, or how a user interface communicates its purpose to a user, or how a developer communicates with the business analysts, without solid communication, I might go so far as to say nothing else matters. What good is a great book if no one reads it? Or more to the point, what good is an awesome design if no one can understand it? What good is a great software business idea if no one can translate the business processes to an application? What good is a great developer who cannot communicate clearly with other developers, users and business analysts?

Finally, the very best thing you can do, of course, is to click on this link and then read the next 120 blog entries. Ha, ha, ho, he, oh man, I crack myself up. J

Good luck!

2009: The year in books (1st half)

Joseph Reddy — Wed, 01 Jul 2009 08:26:48 -0500

For what its worth, here are the books I have read the first half of 2009 and my humble opinions on their content:

SQL Server 2005: Unleashed
Overcoming the Five Dysfunctions of a Team
Elements of Friendly Software Design
Getting Things Done
Data Modeling Made Simple

SQL Server 2005: Unleashed

Ray Rankins, Paul Bertucci, Chris Gallelli, Alext T. Silverstein

I have found that technical books are hard to review for me. If I am not already knowledgeable on the subject then I don’t often know how thorough they are. They also tend to be somewhat dry, not too easy to read for long periods of time. However, they must contain explanations as to why things exist and why features are useful, and why things are arranged the way they are, etc. I also prefer a little opinion with my facts. This book does a good job at this for the most part. Since there are 4 authors it makes sense that some sections did a better job than others in providing real life examples and real-life issues to think about. Technically I am not done reading the book since as of this review I am on page 1116 of 1659. However, I have read enough to know I am generally happy with it and expect to finish it.

It might also seem strange that I am reading a technical book that is 4 years old. However, it had been quite awhile since I have read a pure technical book (as opposed to theory) on databases and at my office we are still on SQL server 2005, furthermore a coworker already owned the book. I’m cheap. For a solid intro to what’s going on in and behind the scenes of SQL Server I think it does a fine job.

Overcoming the Five Dysfunctions of a Team

Patrick Lencioni

Most software developers I know of are part of a team, even if it is a new team every year. I am aware that the team I am on does an adequate job but does not operate as well as I am sure it could. We are definitely not efficient and probably lack definition of common goals among other things. I read this book in an effort to get a better grasp of what those other things might be, and what we as a team could do about it. I did not necessarily find anything revolutionary for me in the book, but I enjoyed reading it and found myself continually nodding in agreement. I am pretty sure there was nothing in the book I disagreed with, but I am clearly more pessimistic than the author about getting teams to work as smooth as he describes in the corporate environment. Right off the bat the author suggests that the team needs to put personal egos and agendas aside and trust our peers enough to be vulnerable and admit our mistakes, etc, etc. Many coworkers I have known cannot even do this with their spouses for Pete’s sake. For my own part, the book is a good reminder of what it means to have a good team and how to be a good team member. I think I’m better for reading the book.

The Elements of Friendly Software Design

Paul Heckel

This book reads like a precursor to About Face. The book has a lot of the same ideas like knowing the user, metaphors, and mental models. It was an easy read, including the author’s thinly-related essay on getting his patents recognized by large corporations that were infringing. The author’s main focus in regards to design was all about communication. I agree 100%. In my own studies and writings I have come to the same conclusion and the book just felt like more validation. Effective communication is what makes things work. Whether it is advertising, movies, books, user interfaces, written code, or team dynamics, communicating clearly allows everything else to happen naturally and with less friction. The book does not offer direct examples of how to use radio buttons or when to use a drop down list versus a list box, etc. That’s not the point. Rather the book really is just essay after essay covering 25+ elements of design. Regardless of whether you are developing a user interface, coding a method, or designing the handle of a car door, the elements should be understood.

Getting Things Done

David Allen

I really liked this book and the nuances the author points out about how we deal with all the tasks on our plate. For example he suggests we need to be able to use our mind to think about things rather than think of them. We need a formal list that holds all the things going on in our lives that tend to clutter our mind and distract us when we are trying to think. Having this list that is always accessible to us allows us to make the transition to thinking about things. Once we have clarified our commitment to each and every task we then need to define doable tasks for each item. In other words we have to define the next step for each item instead of just listing the item somewhere. Our Blackberry calendar should not say Babysitter for Tuesday Night, it should say Call Maureen about babysitting, or clarify with wife about exact time. In other words, it needs to document the next actionable item. Knowing that these things have been thought of frees our mind to focus on whichever tasks we are currently working on. This list also lets us know what tasks could be accomplished when…like waiting for the dentist or with 2 hours of unexpected time at home alone, etc. I liked his ideas so much I decided to implement his basic methods. Although I have not followed his system religiously, what I have changed about my organization of things is working pretty well. I recommend this book to someone who feels like they have too many plates spinning in the air and a few more that they wish were spinning.

Data Modeling Made Simple

Steve Hoberman

Data Modeling Made Simple comes in at a lean 132 pages that effectively provides clear understanding of high-level concepts involved in data modeling while holding off on the low-level details to be covered by other books.

As a developer who approaches a database as just a backend to my business application, I gained further respect for data modeling, even as a parallel process to object modeling. Most of the author's statements of purpose and benefits of the data model match the purpose and benefits of an object model. I believe that doing both only gains me more insight into the business which is of course invaluable.

On more than one occasion after the author suggested something, I found myself thinking, "I hope he explains other situations where you would not want to do that!" And almost without fail two sentences or a paragraph later he explained the alternatives or downsides to the suggestion. To me this is a hallmark of any good book on technology and methods. In fact, just to be picky, I only recall one time he did not do this.

The book is definitely an introduction book and never claims to be more than that. The title even states it is just a simple, practical guide. The chapters are laid out as common questions someone might have about data modeling which makes it an easy read and an easy reference. I will recommend this book to new developers as a quick intro to data modeling and to help arm them with good definitions of terms and high-level explanations of common concepts that they need to understand. I will also recommend this to mid-level and senior developers who still seem to have no basic grasp of data modeling concerns and methods. And lastly I will recommend it to those who seem to think there is a huge gap between object modeling and data modeling in the common business application.

Developer Interview

Joseph Reddy — Thu, 21 May 2009 22:14:13 -0500

I was asked to interview a candidate for a job here at my office. In preparation, I searched the web for good technical questions to update my standard interview sheet which I had not used in years. I found a few web sites that listed questions “every senior developer using .Net should know”. I have been programming for over 20 years and have been using .Net since its inception, so I guess some bureaucrat would label me a senior .Net developer.

I didn’t know more than half the right answers. I must suck.

But I’m here to tell you I don’t suck. In fact, I think I am a definite asset to any development team building mission critical business applications. But I cannot tell you the largest value an int can hold, the maximum amount of memory any single process on Windows can address, or even how to write a for loop in C#. I have mentioned more than once on this site how the hardest thing about development is people, not technology. However, here I was looking for technology questions like these to ask an interviewee. Feels hypocritical.

So I am abandoning the technical questions. Not completely, but if I know the technology they listed on their resume then I can ask one or two questions to get an idea if they are lying on their resume. Here at my office we will ask developers to sit down at a computer and do something rather trivial to show us they were not lying. So assuming they have the experience they claim, what is truly most important is how well I and the other team members will get along with, relate to, and communicate with this developer. It is seriously essential that they share the same point of views in their approach to software development, or at least as many critical aspects as possible. The more years they have under their belt, thus the more biases they have with methods and viewpoints, then the more important this part of the interview becomes. For a new developer out of school who has not been tarnished too much we just have to judge competence.

To that end I am starting to compile questions and statements that can be put forth to a candidate to spur conversation that hopefully gives me better insight into the kind of developing partner they would be. Technically, there are no right answers to these questions; however I do need the answers to be in line with my team’s way of thinking.

Possibilities:

Comments – good, bad - If bad…why? If good…why?
What’s the hardest thing about software development?
What’s the role of a database in the common business application?
Looking at a single method and noting that it can be long, short, efficient, etc. What would you consider its most important aspects?
Do you play a musical instrument, or make movies, or paint, etc?
What’s the role of the GUI?
What are the main benefits to an object-oriented design?
Naming conventions – good, bad, why?, examples…
Exception handling – what’s the point, where, good examples, bad examples
Testing…
What was the point of No Country for Old Men?
What are some of the pitfalls to an OO approach?
Software development life cycle – how does that go?
Dealing with changes in requirements…
Documentation…what’s necessary?
Did you belong to a fraternity/sorority in college?
Do you have a technical certification? If so, what was the motivation to get one?
Name two of your own personal best practices
Name something that seems lots of developers or development teams do that you think is just flat wrong.
If the candidate will help in database design

Nullable columns - bad, good, circumstantial?
How do you feel about stored procedures - benefits, drawbacks, misuse?
Feelings on auto numbers / surrogate keys / virtual keys /natural keys. Benefits and drawbacks

What’s your favorite kind of work related to a software developer’s job?
What makes a developer a good developer?
Based on something on their resume that is highly-technical that you believe needs a very good reason to be used, ask them about situations that required the use of the technology.
What are the last two books you read related to your job as a developer?
- Did you agree with the author's ideologies?
What traits do you have that might constitute a weakness in regards to you as a programmer?
A question to see how they would react to an impossible situation. Like a stakeholder asking for a ridiculous time schedule or a boss that says something has to be correct and done by morning and upon finding problems with a critical detail you cannot reach boss on phone, etc.
Do you participate in any open source projects?
What’s the purpose of a business object?
Talk a bit about the involvement on a development team of the users and business analysts.

I think it’s important that we don’t say too much, or lead the interviewee too much and by no means should we argue with them. We just want to get them talking and maybe take notes on some of the ideas they profess. Got any more ideas?

Where Does Business Logic Go?

Joseph Reddy — Thu, 23 Apr 2009 21:39:33 -0500

Encapsulating Business Logic

Recently I was asked for my 2 cents in regards to how I might encapsulate some business logic (business logic defined here). Over the course of the discussion, I realized that I tend to follow a mental checklist of sorts in order to make sure I am implementing encapsulation correctly. Paraphrasing Einstein: if I understand something well enough then I should be able to explain it simply. So what follows below is my attempt to explain encapsulating business logic simply in order to see if I understand it well enough. Following the explanation is a quick example.

Encapsulating Business Logic Checklist

Clarify the logic
Capture the logic
Make the logic easily found
Make the logic easily testable
Make the logic hard to mess up

Clarify the Logic

Write something down. Even in an ideal word where all requirements and business rules are written down in formal documents, we often need to restate words in the context of the system to make sure we are on the same page as the business analyst. I have done everything from typing up an official document to just having the business expert look over my shoulder at the comments of a routine. Whatever fits you and your context is great, just do it.

Capture the Logic

Regardless of where I put the logic at the end of the day, first I just want to start capturing it in code, thinking about it from a code point of view. This is the first stab at design separated from all other concerns as I start writing code to implement the logic. The classes involved are determined as I go through typical black-box thinking: Given A, B, and C how do I determine D? This naturally leads to the next step of making this logic easily found.

Make the Logic Easily Found

I need to make this logic easily found for the next guy who is going to update this logic or gasp, fix my bugs. As an object-oriented developer, I know the business logic belongs in an object, but which one? The short answer is…the obvious one. Often a particular object seems to be the most natural choice and we don’t give it much thought. However, when multiple objects are involved the general rule is to pick the object that has the most data involved. If multiple objects appear equally involved THEN JUST PICK ONE, you’re thinking about it too much now.

Make the Logic Easily Testable

Business logic is arguably the most important code you will write. It determines how much should be paid or charged, calculates values, determines answers, figures whether a missile should zig or zag, etc, etc, etc. If you are going to bother writing any tests, test your business logic. Furthermore, make the tests so fast and easy to run that no one has a problem with running the tests all the time. If you find you can’t easily and repeatedly test your business logic because it requires database connectivity, complex object creation, or whatever, then think about changing the design. It’s also true that making your logic easily testable with solid tests can go a long way towards clarifying the logic and design. This is one of the touted benefits of test-driven development.

Make the Logic Hard to Mess Up

Those who make the leap to programming objects as opposed to just programming with objects will see a huge improvement in quality simply because things become harder to mess up. There are many things we can do, but two common approaches include making objects for any business concept and making objects immutable. For example, if a password has to be more than 3 characters but less than 10 and include letters and numbers then create a Password object that encapsulates these business rules and has methods for accessing them. It should be impossible for invalid passwords to be bouncing around the business layer of an application. If an Email requires an IP address of an SMTP server to send itself, then do not make a property called IP address that may or may not be set at the whim of the caller, or get changed somehow during a process. Make the IP address required upon construction and unchangeable. The users of that Email object are much less likely to mess things up.

Simple Example

For the sake of discussion, another developer sent me a simple case. I like simple cases because then we can focus more on the process and less on the complexities of the example. However, I’m sure if you use your imagination you could apply the checklist to more complex scenarios.

I have a class I’m creating called Message Header, and I need to increment a value (Message Number) each time I create an instance of the class based on a previous message number.

Clarify the logic

After a few emails we established the following details about the business logic

At this point we don’t know where the last message number comes from
Message Number is an attribute of Message Header
The new number should always be the next even number (2 more than the previous)
The new number should always be between 2 and 9998 (inclusive)
After 9998 the message number should reset to 2

Capture the logic

I create a function called DetermineNextMessageNumber that takes in the previous message number. Code is written to encapsulate the logic above. Defensive code is added to throw an exception with the kitchen sink if expected assumptions are not met – like assuming the previous message number is always even.

Make the logic easily found

The obvious choice according to the developer was the MessageHeader class, so I add the method as an internal/friend static/shared method to the MessageHeader class.

Make the logic easily testable

I create 5 quick tests to test the logic: a normal case - passing in the number 6, two edge cases – passing in zero and 9998, and two possible extremes – passing in -50 and 55223. This prompts me to ask the business analyst what to do in these extreme cases. He claims both are exceedingly unlikely. So I figure my defensive coding with the kitchen sink will be perfect for when the cases do happen. My tests require no database access and no complicated object building. No changes seem to be needed, the method is easily testable.

Make the logic hard to mess up

I don’t create objects with settable attributes by default so I know the user could not easily forget to set the Message Number. However, I realize that someone could create a Message Header and not realize there is business logic that determines the correct next number. To fix this I change the constructor on the Message Header class to take in the PreviousMessageNumber. The constructor will then call the DetermineNextMessageNumber making sure that a coder cannot generate a Message Header without applying the appropriate logic. Since the constructor handles the logic I realize I can reduce scope issues by making my DetermineNextMessageNumber routine private. Suuuhhhweeeet. For half a second I think that maybe I should make a MessageNumber object that will guarantee a valid integer between 2 and 9998 and thus separate concerns more, etc. However, the expert said it is rare, and I am throwing in the kitchen sink in case it does happen….hmmmm, I think the design is good enough for now.

Summary

Get your logic right, get it in code in the correct place with good tests, and design so that the next guy will have a hard time messing it up.

When I see the code of developers trying to do more than just object-based code the most common blunder seems to be leaving business logic all over the place. The most common misplacement seems to be in user interfaces, however, well-meaning developers often move the logic out of user interfaces but then misplace the logic in factory code, service classes, stored procedures, etc. When object-thinking is applied I think logic starts to naturally fall into place without much thinking or time-consuming analysis.

What is Business Logic?

Joseph Reddy — Thu, 16 Apr 2009 08:54:15 -0500

What is Business Logic?

Business: Commercial enterprise: the activity of providing goods and or services involving financial, commercial and or industrial aspects

Logic: The principles that guide reasoning within a given field or situation

Business logic code is the code that applies the principles that guide reasoning within the business. Sounds fancy, but in fact it is just the code that makes decisions, answers questions, and applies rules. One might argue that in the common business application the business logic code is the most important code. The code you cannot write unless you understand the business and as such is often defined by experts in the field.

What is not business logic code?

In short: all the other code. Often the common business application also requires code to handle user interaction via graphical user interface components. There is often code for database access, code for capturing process algorithms, code for handling security, code for logging interaction or auditing events, code for managing errors, code for wrapping external services or components, etc. These subsystems are all required to complete the application, but are often not directly tied to the business itself. As mentioned above, business logic is defined by a subject matter expert from the business the application is being built for, however the developer or other related technical authority is often the subject matter expert for this other code.

This is so clear, could you please add some confusion?

Yes, yes I can. The subsystems noted above (data access, user interface code, etc) also have principles that guide the reasoning related to them. So although these subsystems are not tied directly to the business at hand, they do have their own business to attend to and so the logic involved is also technically business logic. This is important for the object-oriented developer since the objects created to handle these subsystems should also be responsible for their own related business which of course is not the business of the application...clearly. This is worth noting because often object-oriented developers drop their respected OO principles when working in these other subsystems outside of what they would consider business logic. I did just that until it dawned on me that I was missing all the benefits of an OO design outside of business code.

Why is it important to identify business logic?

Business changes frequently and we have to know where to look, what to change, and how to easily test our changes
When discussing the logic with subject matter experts after it has been implemented, we need that logic isolated and at the right level of abstraction without peripheral distractions to minimize logic-to-code translation
So the business logic code can be kept separate from other code to make sure changing either has little to no affect on the other. Rude developers have a habit of spreading business logic all over an application from the user interface through stored procedures
We have to be sure not to duplicate business logic so when it needs to change (as it is highly prone to do) we make sure the logic is changed and fixed for all code dependent on that logic
Business logic is often tied back to requirements to make sure features are implemented correctly

See also:

Business Object

Your object-oriented program is not object-oriented

What's the diff?

The Next Guy

Joseph Reddy — Wed, 08 Apr 2009 21:40:23 -0500

Who is this next guy and why do I care about him or her?
One of my favorite quotes is attributed to Martin Golding, "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." The psychopath is The Next Guy.

Often senior developers write new applications, write the hardest parts of an application, or at least set the standards to be used in writing an application. However it is usually junior and newbie developers who actually spend the most time in the code in what is the longest phase of any application: maintenance. So junior and newbie developers are The Next Guy.

Often we write code when our heads are totally wrapped around the subject matter and the technologies involved. However in two months or even less, when we go back to work with the code it might as well have been written by someone else. We are The Next Guy in this case who cannot recall what the heck is going on.

In the if-you-have-not-read-it-yet-stop-writing-code-and-read-it-first-then-get-back-to-work book Code Complete, the author reiterates a long established truth about programming: Write code for people first, computers second because computers can read ugly code but they don't have to debug and enhance it. In other words, you must keep The Next Guy in mind when writing code, it is imperative.

How do you keep the next guy in mind?

This can be done in many ways, too numerous to record here but I’ll list a few of my favorites or greatest related pet peeves when I am the next guy.

If I am the next guy, do not make me think about, work with, or understand anything more than I absolutely have to in order to get my job done. Try to apply some level of a separation of concerns for my sake. The notion is simple really. It is easier to think about things, work with things, understand things and communicate things when we only think, work, understand, and communicate with the least amount of concerns as possible.
Follow some coding standards so I don’t have to constantly figure out what some new convention is supposed to mean as it changes from module to module. Any standards please! If someone else already started the coding on a project using a particular convention then use theirs, I don’t care what your preference is.
Magic data values make me mad, like violent psychopath mad.

Widget.DetermineThis(5, “Begin”, false) – Huh?

Write code using the core framework and basic functionality of your language. Stick to what you would expect a new developer in the chosen language and framework to understand. Anything else should be strongly contested and verified as necessary.

We all know (or have been) the developer who reads a chapter on threading and now all the sudden everything is a needle and requires some good threading. Oooh, Microsoft LINQ I’m doing that! Generics, cool it’s not just for collections anymore. Oh yeah, I’m stick’n AJAX on our website. Desktop apps are so 90s! XML kicks up the cool factor! Real objects don’t expose any data! Just stop!
The best business application developers are not more productive because they know all the intricacies of a language. Language-certified developers scare the hell out of me. Don’t make things more complex than they absolutely have to be because I want to get in, get out, and get testing.

In an ideal world, well-written code does not require comments. In the real world, even well-written code could use some comments of intent. Well-written comments are the Excedrin to the migraine pain of bad code.
Use objects. At least object-based, but consider object-oriented. And no, I do not consider rudimentary knowledge of objects and object-oriented thinking to be above the newbie developer. I started teaching my daughter programming when she was nine and the first thing I taught her was what an object is. I explained it is the building block of everything and all the "smart" code you'll write is inside them. Some 10-year development veterans using an OO language like VB.Net still don’t get that.
Apply a little defensive coding to help the next guy figure out what went wrong after they have broken the code. For example, any time you have a case statement always have an else block to check for the unexpected. Adding a new enumeration should make the code bomb if somewhere in the bowels of the code that enumeration was not expected.
I have to stop. I could go on all night with this. However since these were the first 7 things to pop in my head I am going with them.

The Pit Stop

Joseph Reddy — Fri, 27 Mar 2009 08:06:30 -0500

One upon a time there were 3 little race car drivers

There are 3 drivers in a 50-lap race driving their cars as fast and as hard as can be expected in a race to the finish. After 25 laps their tires start to thin out, gasoline gets low, even paint starts to chip off the hood of their cars. Driver 1 and 2 are driving steady and fast but trail driver 3 by about 5 car-lengths as driver 3 drives at unsafe speeds. Driver 1 pulls over for a pit stop and gets 4 new tires and a full tank of gas. Driver 2 does the same but also touches up the chipped paint. Driver 3 decides he has no time for stopping and skips the pit stop resulting in an impressive 2-lap lead on the other cars.

Driver 3 blows out one of his thinned-out tires at lap 85, but is able to hobble forward with 3 tires and a rim. By lap 90 the other drivers with good tires are nearly caught up. At lap 95 driver 3 blows another tire and realizes he in running on fumes. Driver 3 knows he needs one last heroic effort to beat the two cars that are now right on his tail. He switches to a higher gear and guns the engine coming out of a turn. His bare tires can’t take the explosive speed and he careens across the track and into the wall destroying the car and nearly killing him. Driver 1 wins the race with driver 2 about 20 car-lengths behind.

If you have made mistakes, even serious ones, there is always another chance for you. What we call failure is not the falling down but the staying down. - Mary Pickford

Driver 3’s mistakes seem obvious even to someone like me who knows little of car racing. Everyone knows he has to go fast to win a race, but not to the point of being reckless. Everyone knows he will have to take a pit stop, obviously stopping his forward progress, but it is time well-invested to ensure he can finish the race. Everyone knows the more reckless he drives, and the worse shape his car is in will have a cumulative affect making him drive more reckless and deteriorate his car even further to the point where he cannot race anymore.

Driver 2’s mistake is a little less obvious but he did lose the race for a reason. He was smart to take a pit stop, however he was not smart about what he chose to do with his time there. Driver 1 made the smart decision to leave the chipped paint for another time and only change what was required to make sure the race could be won.

Those who make the worst use of their time are the first to complain of its shortness. – Jean de La Bruysre

At this very moment development teams around the world are building applications without pit stops. There’s a good chance you know of one, are a part of one now, were in the past, or will be in the future because it is an epidemic that is more prevalent than it ought to be.

The way I see it there are two kinds of pit stops and more than one way to handle them. There is the concept of mini-pit stops in software development called refactoring which has become so mainstream that refactoring options are now built into Visual Studio. Refactoring is the concept of taking time to improve existing code without changing functionality. The value is often unperceivable by the naïve developer and of course management. In general, right after code is written, when a new feature is added or a bug is fixed, we must always give some thought to changing the design so the new feature would be easier to add, the feature would be easier to update, or the bug could never happen again.

There is also the concept of a large pit stop that is obviously more time consuming and painful. The large pit stop is often attributed to not taking enough previous smaller pit stops. The bigger the pit stop is the more likely it will be put off. The more it is put off the bigger the need becomes until the race car (application) is so beat up, so distorted and uncontrollable, that it falls apart and management decides we have to buy a new car (rewrite). Not stopping for the smaller pit stops ends up costing the business much more money in the end.

There is still much to debate about when it comes to pit stops along the lines of when to take them and what to do while we are stopped. Driver 2 made the mistake in his pit stop to touch up his paint which was cosmetic and had no affect on the future of the race, and in fact cost him the race. Likewise, developers need to be judicious about what gets changed when they invest time to do so. We have a tendency to want to make things look familiar to us, do them our way. In affect we are just skinning the cat a different way and there is no improvement, or the improvement is marginal at best. The best pit stoppers know why they would make any change before making it so they can better foresee the impact. Another possible pitfall of the pit stop is what author Fred Brooks calls the Second System Effect where developers tend to over-engineer a solution now that they have time to address everything they couldn’t the first time around. Like skinning the cat and making cosmetic changes, over-engineering has to be held in check.

Quality is not an act, it is a habit. - Aristotle

The need for time-consuming pit stops can be alleviated by any kind of quality control a development team can muster. This might be achieved by code reviews, pair programming, an easy testing framework, or simply best practices and standards agreed upon by the developers. I state they can be alleviated in order to clarify that they cannot be removed entirely. No professional application worth its bytes can survive and have a decent return on investment without refactoring. Duct tape, spit and glue can only hold things together for so long, eventually broken applications completely fall apart. It is always then we realize that a little preventative maintenance could have helped. An ounce of prevention is worth a pound of cure as Ben Franklin would say.

The inexperienced view is that the methods used to get an application up and running or to figure out how to do something can be the same methods used to maintain, update and fix an application. Often in an effort to get an application to market, electrify a client, impress a boss, just figure something out, or get some dollars rolling in we do what ever is necessary to get something working. However, it is patently absurd to keep banging away on an application with a hammer when the application and its context have evolved in to what is no longer a nail.

In this blog I tend only to deal with software concepts that affect the common business application. The business application has to be one that is intended to last as long as the business and make it more profitable. However a lack of quality control, in this case the failure to recognize the necessity of pit stops, seems to be a major killer of applications, developer’s jobs, and ultimately businesses. Though one could argue that this problem often creates more jobs as managers try adding more developers to fix their problems as opposed to ever addressing the fundamental issue. Right now there are too many businesses losing profit by paying too many developers to maintain applications that should require less to do so.

3 years later...

Joseph Reddy — Tue, 10 Mar 2009 08:01:35 -0500

If you can’t explain it simply, you don’t understand it well enough. - Albert Einstein.

I think it is safe to say that Albert enjoyed thinking things through until he understood them well enough to explain them simply. 3 years ago to the day I started a blog to challenge myself to see if I understood software development practices well enough to explain them simply. Often I fail with verbose explanations of concepts, which according to Einstein means I must not have a complete grasp of them yet. But overall, I consider the blog a success. Granted with the insignificant number of subscribers and only a couple hundred page views a month, I don’t think I’ll be quitting my day job. However, that was never the point.

By thinking things through, verbalizing them, and discussing them outside of myself, I have gotten a clearer understanding of the whats and the whys of development. I’ll go so far as to say that over the past 3 years the blog, the 65 pages of notes yet to be clarified and simplified, and the ensuing conversations have been the main catalyst for my improvement and overall development as a software developer.

For what it’s worth, I recommend the same for any developer. Try writing down what you think is most important about development, or what drives you crazy etc. You may find that you can’t, because you can’t verbalize what are just abstract judgments. You may also learn some things are not as important as you thought. Best of luck.

Scratched Windows

Joseph Reddy — Thu, 05 Mar 2009 11:15:05 -0600

One of my favorite metaphors in regards to software development is that of Broken Windows. I first read about the theory of Broken Windows three years ago in the book the Pragmatic Programmer. The theory comes from research done in inner-city neighborhoods where a psychologist noted that when broken windows were not quickly fixed in buildings a sense of abandonment and general culture of disregard for the building took hold. Soon graffiti, trash, and more vandalism became common place. The solution: don’t allow broken windows in the first place, but more importantly, fix them immediately. When the windows were fixed quickly the exact opposite culture set in. A culture of respect and perceived quality soon meant that fewer windows, if any at all, would be broken in the future.

This parallels software development if you consider things like quick hacks, poor error handling, missing abstractions, lack of standards, etc as broken windows. When they are tolerated the same theory suggests that the culture we are instilling only perpetuates more trash and development-vandalism in our project. This is one truism about development that I believe very strongly.

If only software development broken windows were so obvious, so definite. Recently I mentioned to another developer that a metaphorical window was broken, he suggested it was merely scratched. Later I proved that a missing abstraction broken window led to breaking a standard we had all agreed to and I was concerned about what else these broken windows would lead to. The other developer claimed I was essentially using a slippery slope argument to claim one thing will lead to another. But that’s just it, that’s the point of the broken windows theory. He also suggested that he could track the windows and step in before it got too out of hand. I’m not so sure you can easily change the development culture surrounding an application after so long.

In a previous blog entry I mentioned the benefits of trying to give more than you take in terms of design choices when working with another developer. I believe in the above examples the developer who was allowing the broken windows was doing so in an effort to give wherever he could, an admirable thing to do. To keep the metaphor going, one might argue that he had to give up a few broken windows so he could gain a few steel doors. Is there risk that the broken windows will lead to more problems? Yes, I think it was even proven. However, as I have often stated before, it is also nearly definite that the hardest thing about software development is “other people”. Sometimes a few broken windows are required to maintain goodwill and a productive development culture among those people.

A Sixth U of Design Debates

Joseph Reddy — Tue, 24 Feb 2009 08:28:11 -0600

About a year and a half ago I had written a blog entry called the 3 U's of Deisgn Debates. The entry is about things I need to keep in mind whenever debating design, best practices, or truly anything at all. Months later I added a 4th concept, and then a 5th, and now today I have a 6th. So along with Unclear Requirements, Undefined Scope, Underlying Fundamental Opinion, Unrecognized Context, and Uneven Give and Take, I propose No Ultimate Decision.

No Ultimate Decision

During a debate everyone wants to get heard and everyone’s egos really want their own ideas to be chosen in group consensus. We are careful to protect core beliefs that we hold dear (even if we are not sure why we hold them so dear), we might make snap judgments and be uncharacteristically inflexible in regard to them. It’s our nature; we are in the heat of battle and this is our only chance to get to the right answer, to the correct ultimate decision on the matter.

The first mistake in a discussion that is warmly if not hotly contested is to even try to make a final or ultimate decision right then and there. A better option is to make sure notes are taken and positions summarized and made clear. Secondly, everyone involved should be left alone to absorb what has been said. A conscientious developer will often back off snap judgments they made and possibly rethink their position while the words of other debaters bounce around their heads. They will also remember the things they did not think of in the meeting, like possibly the other 5 U’s of design debates. So in a nutshell, hold off making a final decision after a single design debate.

The second mistake related to an ultimate decision is a little more touchy-feely. We seem to sometimes equate giving in with completely disregarding our beliefs. We seem to feel that going with a different option somehow negates all we have learned, or means every time we did it differently we were doing it wrong. We make the mistake of feeling that somehow this one case becomes the ultimate decision, the ultimate word on the matter. I noticed this a lot recently when talking about surrogate keys, multi-part keys, and natural keys with a bunch of different developers. I had many good conversations, but I also had useless ones where a staunch defender of a method seemed afraid that if they gave in or admitted benefits to the other options, that they somehow negated all the great work they have done in the past.

We have to keep in mind that no decision we make about development is the final word on the matter. I have been writing software for over 20 years and no two applications have ever been written the exact same way. The “best” way to do darn near anything changes with my experiences along with the influences of those around me (as it should be). I have to remember not to rush to a perceived ultimate decision, and in the end remember that there really is no such thing anyway.

A Fifth U of Design Debates

Joseph Reddy — Mon, 23 Feb 2009 12:07:26 -0600

About a year and a half ago I had written a blog entry called the 3 U's of Deisgn Debates. The entry is about things I need to keep in mind whenever debating design, best practices, or truly anything at all. Months later I added a 4th concept, and now today I have a 5th. So along with Unclear Requirements, Undefined Scope, Underlying Fundamental Opinion, and Unrecognized Context, I now offer Uneven Give and Take.

Uneven Give and Take

8 years ago at the start of a project with another developer, I adopted that developer’s variable naming convention. We had agreed that the scope of a variable should be denoted in the name, but that was the extent of our agreement. Unlike me, he liked to note the data type, liked to always use a 3 letter identifier, and to move the abbreviation to the end of the name. In my life I have never seen another example of any code any where that looks similar to this convention. I physically shivered the first time I typed LastName_mStr instead of _LastName. Now, ask me 8 years and 10,000+ lines of code later if it bothers me at all to type LastName_mStr. Of course it doesn’t. I am used to it. The verbose extensions flitter off my fingertips without any thought.

Being aware of an Uneven Give and Take refers at once to compromise, but also to choosing our battles wisely. With any good development team, there should be healthy discussion about best practices for the context of the application, and many small and large design decisions. If the team really has their act together this would also include some pair programming and or peer code reviews. The conscientious developer (debater) should know why they do what they do, and try to stay keenly aware of what is important and what might just be noise. When in these discussions it benefits us to try to give more often than we take in order to help foster a sense of compromise and to save up "debate goodwill" for when we find a topic we really should hold our ground on. If you try to do this, chances are you will give in just enough. As a developer in my office routinely says, sometimes you just need to smile, nod, and say OK. What is understood is that you are biting your tongue, saving both your breath and debate-points for another debate that matters more.

Are there any benefits to adding data types to variables or moving the scope identifier to the end of the variable instead of the beginning? Sure there are! But they feel negligible to me and the convention of course has its own drawbacks. However, on a more human level, there are many benefits to smiling, nodding and saying OK. This is by no means meant to be patronizing or condescending. You are deciding that what ever your beef is with the idea, it is not dangerous or problematic enough to bother fighting over. Ask yourself these questions: "Can I live with that?" "Is that really problematic, or just ugly, or different from what I am used to?" "Is this a good time to give, let them have their way?"

I would even argue that based on my experience, uneven giving and taking leads to a lack of standards, people avoiding debates, hiding their methods from each other, voting against code reviews, and just generally not getting along on a development team. This can be a major contributor to team deterioration leading to a guy in a room and or going dark.

Why oh why

Joseph Reddy — Fri, 13 Feb 2009 10:14:50 -0600

For me, in software development, it is all about why. I feel a very strong need to understand why I am doing everything and anything I do. Furthermore, I am upset with myself when I cannot clearly state why, and on the flip side take pride in knowing why: why I choose a minimum of three layers in darn near any application, why I rarely if ever read books on a language, why I don’t blindly choose auto numbers for primary keys in databases, why I prefer business-object-oriented development, why I don’t bother arguing with people about how they want to define scope on their variables, etc, etc, etc, etc, etc, etc.

The author of one of the books I am currently reading (Getting Things Done) stresses that getting anything done starts from understanding why we are trying to get anything done in the first place. There is a real problem if we cannot explain why we take any action, and if we cannot agree on why we are taking action.

I feel validated today. I guarantee you there is more than one developer in your midst right now who cannot tell you why he or she does things the way they do. “That’s how everyone does it,” or “It’s better,” or “It’s easier”, or "It's simpler" do not count. I’m looking for a deeper understanding of purpose. **

Want a telling interview with a perspective hire? Ask them why they do the things they say they do. Do they put little prefixes on variables to denote data type? Ask them why. Do they employ object-oriented development techniques? Ask them why.

Want to be a better developer? Work to understand why you do the things you do and to understand why you don't do some other things. Sounds like common sense, but appears not to be commonly practiced.

**Side Note: One short answer that I have becoming increasingly alright with is "I am comfortable with this." If you understand both sides of a debate, and everything seems relatively even, being comfortable with a decision can easily tip the scales as the comfort level may make you more efficient and even happier.

2008: The year in books (2nd half)

Joseph Reddy — Thu, 08 Jan 2009 09:16:29 -0600

First half of the year books (blog entry from June):
- Manage It! By Johanna Rothman
- Object Models: Strategies, Patterns, and Applications by Peter Coad
- Prefactoring: Extreme Abstraction, Extreme Separation, and Extreme Readability by Ken Pugh
- Object-Oriented Program Design: With Examples in C++ by Mark Mullin
- Building Object Applications that Work by Scott Ambler

Second half of the year in books and my humble opinions on their content:

- About Face 2.0

- Object Thinking

- Systemantics: How Systems Work and Especially How They Fail

The list is shorter than usual thanks to two technical books I read, ahem, skimmed for information, but had no real intention of reading cover-to-cover:

- IIS7 Implementation and Administration

- SharePoint 2007 Unleashed.

About Face 2.0

Alan Cooper and Robert Reiman

About Face is a book I have contemplated reading for over 10 years but shied away because I am not a big fan of user interface work. About Face 2.0 is the second release of that book. (There is in fact a 3.0 version of this book put out in 2007.) I’m glad I finally got around to it. Like the book, I can put off UI development, but eventually I have to face reality and get it done, and get it done right.

The About Face author builds heavily on the most memorable aspect of another book I recommend called The Design of Every Day Things. This central theme is that we build the user interface to reflect the user’s model of the system, not our model and definitely not the implementation model. (I have a few notes here on this.) The book stresses making the user happy which requires us understanding their model along with their wants, needs, context, and motivation.

The writers are fanatics as you would imagine they would be to take the time to write a book on a subject obviously near and dear to their hearts. Some of their advice may seem a little impractical for the common business application developer, for example, cutting out people from magazines to help put faces on users. That said, this is not exactly bad advice, and very similar to the efforts Microsoft put into creating the personas of Mort, Elvis and Einstein. There is plenty of practical advice beyond the equivocal “user model” like trying to provide modeless feedback, not popping up windows for everything, designing for the probable case and providing for the possible, anticipating needs, avoiding clutter and too much on a single window, etc, etc. Great stuff for new developers and fantastic reminders for the experienced ones. I should skim my notes from this book every time I am about to embark on some UI development.

Object Thinking

David West

I can’t say I would recommend this book, but I did enjoy it. I like reading about people’s opinions and experiences applying object-oriented methodologies to applications, regardless if I agree or can even relate. The author attempts to explain how object-oriented developers have to change their point of view when designing software to a near radical extent. I agree there has to be a point-of-view shift, but the shift he asks developers to make outside of the context of a common business application seemed too, well, too out of context. Like many OO books it suffers from OO examples that are not from the common business application, but from a real-time application like a game, or user-interface-based app like a word processor, etc.

I have made it clear through out my blog that I am a huge proponent of object-oriented methodologies, but argue that the standard heuristics have to be adjusted to sit well with the common business application. This author is not in the same boat as me and often refers to objects displaying themselves on user interfaces, and relying on events to link up functionality, etc.

The author also divides up developers into two groups: those that are agile and those that prefer big upfront engineering methods. He completely ignores the hordes of no-separation-of-concerns-hacking crowd which makes up the majority of new and junior developers. This bothered me, but he may do this on purpose as he might be assuming they would never read his book in the first place.

I’m not sure who I would recommend this book to. I think the newer developer would be confused and the practical OO developer would be bemused. I assume it might be good for the strict engineering type OO developer he refers to. The book then reads like a case for agile development for that reader.

Systemantics: How Systems Work and Especially How They Fail

John Gall

Systemantics was probably my favorite read of the year. Like The Design of Everyday Things, this book is not about software development, at least not directly. This book addresses all the things that are arguably true about systems. The book refers to large systems like government and public school systems, and medium systems like city garbage collection, and even smaller systems like families, or a system for managing a small group of employees. These systems are all set up to solve or at least manage a problem the same way we develop software systems to do the same.

The author refers back and forth to these common systems as he explains over 20 truisms of systems, especially large ones. Some of my favorites include:

First rule of systems design: do without out one if possible
New systems mean new problems
A large system produced by expanding a smaller system will not behave like the smaller system
Things are as they appear to be, not what they are

The book is written in a very lighthearted yet serious way which makes it easy to read, even funny. Everywhere, things are not working well and those outside of the systems that are failing are sure they could fix them if only their ideas were universally adopted. However, this book admittedly offers no solution. There is no single method to follow and all axioms are too fundamental for direct application. Rather the axioms provide clues and guidance to awareness of what makes a particular system faulty. The Systemantics student, understanding the risk of failure, even catastrophic failure, knows that the undertaking should only be begun where the present evil is very clear and the consequences of utter failure are no more unbearable than the original unsatisfactory situation.

Simple Object Pattern: Type Object

Joseph Reddy — Mon, 05 Jan 2009 08:11:35 -0600

Intent

Create an object that defines the kind of possibilities available for a parent object and encapsulates the attributes and methods of that type.

Why

Clarity. A designer may misname an object when not realizing the concept is a type of something, the definition of something and not the actual thing. This almost always leads to the the actual thing being misnamed.

Implementation Notes

When we realize the concept we are modeling is a type of something, we create a class called SomethingType (or SomethingDef(inition)).

Just identifying that there is such a thing as a stereotype/pattern called Type helps in model design and understanding. Better names for classes are created and often odd inheritance relatioships are avoided.

A Type Object might be modeled as a Value object or Entity object depending on the model.

Example:

We have different kinds of vehicles: cars, trucks, vans and SUVs. Without thinking about the concept of Type objects a modeler may create a class called Vehicle that can be a Car, Truck, Van, or SUV. Eventually they run into trouble when they want to add an attribute to a Truck that does not quite belong. They create a new class with a poor name like ActualVehicle, UsedVehicle, etc. The modeler may never realize that their first object is a type of Vehicle and should encapsulate everything related to the type, not an actual Vehicle. Their second object is the true Vehicle.

Sounds obvious but I have stumbled across designs that have done this with User objects, Event objects, and more. In the User case it resulted in an object called ClientUser which was of course not part of the Universal Model. The Event case resulted in a second object called a Scheduled Event which one would assume was a special kind of Event until you looked under the hood and saw that the Event class was really just a type of an Event. Both examples created misleading models and some other poor design off-shoots simply because the concept of the Type stereotype was not implemented.

Click here to view list of all Simple Object Patterns

Focus

Joseph Reddy — Thu, 04 Dec 2008 11:14:13 -0600

"Our thoughts create our reality -- where we put our focus is the direction we tend to go.”
Peter McWilliams

I have often stated that a tell-tale sign of a data-centric application design is designing the data storage first. Obviously database tables are not part of the problem domain, they are implementation details. Designing tables first means I am concerning myself with how I am going to implement something. I am no closer to action, action that solves a problem or even better, gets me closer to understanding the problem and its obstacles better. What I should be doing is learning what is involved in the problem and what is responsible for doing what, responsible for figuring out what.

So we shun the table design and focus on business objects because they are the whats, not the hows! However, here is where I often still make a mistake. I end up focusing on what the code will look like, the structure of it all, the objects I am sure are involved, the objects that will contain this and the objects that will contain that. In the end, this approach is not much better than the data-table-design-first approach as the focus is still on how things will be organized and implemented without any real concern with solving the problem.

Those in the test driven design/development (TDD) club (which I am not exactly a full blown member) realize this and propose a solution that requires we write tests first. This forces us to focus in on responsibility and let the need for certain things to get calculated and determined drive what objects will exist. After that happens we can then figure out how those objects will do their calculations and determinations, and we will figure out how those objects will be persisted.

The truth is that the first step is to understand the domain, or in the case of a new feature we need to understand a subset of the domain. Often experienced developers can envision what objects will be required to support something after they get a good understanding of it. In the common business application there is often a correlation between an object and a table so one can argue we “know” what tables will be needed. Often we are right, or it at least it feels like we have guessed right because we make it work with what we have already created anyway. We build ourselves an object model or data schema box without realizing it is keeping us from thinking outside the box.

So when we think it through and write something down before getting started, make sure you think through the responsibilities required of objects and choose objects from possible candidates in the domain. Figuring out what exactly is going to happen (not how) and who should do it (what object) is your priority, your focus. When every responsibility is accounted for, then you have something that solves a problem. A data table or an object with data does not handle a responsibility, they do not solve problems, they only support the effort.

Generally Speaking...

Joseph Reddy — Tue, 18 Nov 2008 08:24:12 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is an index of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

- The best software is never written

- Write something down
- Practice, practice, practice

- It is not about how fast you can get something done
- No spaghetti or balls of mud

- There are at least 3 layers to every application

- Favor theory over rules
- Programming a computer is easy
- Everyone writes hacks
- Business-Object-Oriented should be standard operating procedure
- Make the user more effective

Generally speaking...Make the user more effective

Joseph Reddy — Fri, 14 Nov 2008 16:37:28 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Applications (especially the user interface portion) should serve the user by making the user more effective, not more flexible. We have the tendency to try to create user interfaces that allow a user to do everything, have full control. At worst developers build an application as just a front end to a database essentially giving the user a database table editor. If that's all we were meant to do we would all be using Microsoft Access to create database front-ends.

Software should be a tool to help users do their job better. This requires that we work hard to understand their job. We need to gain understanding beyond the tasks they must complete and instead strive to understand their goals. This may sound a little touchy-feely but in the end it is really about learning the user's business and creating an application that makes the user more effective at their job. Replacing a file cabinet with a computerized file cabinet is not application development, it's called shifting the burden.

Generally speaking...Business-Object-Oriented should be standard operating procedure

Joseph Reddy — Thu, 13 Nov 2008 17:41:33 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Create an object model that models the business. Put business logic inside the objects, put process logic inside the services, and put implementation code in utility classes. Life as a business application developer gets immeasurably easier when you follow these simple, flexible, and technology-independent patterns.

Generally speaking...Everyone writes hacks

Joseph Reddy — Thu, 13 Nov 2008 08:19:03 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Everyone has to write a hack from time to time thanks to time constraints and other imposing factors. And by hack I mean code that we know is way less than perfect, smells bad but left alone, or a change in a model that is much different than maybe the database that supports the application. I often hack together methods on an object with full knowledge that my tests will bring out its dark side and help me refactor it later. What separates the masters from the merely competent is how hacks are written and what happens afterwards. When I stumble over my own hacks from a year ago I am reminded why I am not yet the master I wish to be.

Writing hacks should take place as deep as possible in the application. When we do write a hack we need to put the hack as deep in the code as possible so no code above it ever has to worry about the same issue again. Unfortunately some of the most hacked up applications have no choice but to implement hacks right in the user interface, the absolute last place where you want to do it.

It is too easy to just throw up our hands and decide we'll just have to hack something together so it works. When a hack is written it should be officially documented and the fix should be added to the top of the to-do list for the next release. Any and all implications to the model must be understood by all stakeholders.

No Broken Window Syndrome!

Generally speaking...Programming a computer is easy

Joseph Reddy — Wed, 12 Nov 2008 08:06:44 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Programming a computer is easy, productive and clear communication is very hard.

Work on the latter. <-- Universal Model

Work on the latter. <-- Object-Oriented Analysis and Design with Applications [Booch]

Work on the latter. <-- Communication Skills 101

Work on the latter. <-- Communication Skills 102 . . .

Work on the latter. <-- Start thinking out loud about what you think you know

Work on the latter. <-- Difficult Conversations: How to Discuss what Matters Most [Stone]

Generally speaking...Favor theory over rules

Joseph Reddy — Tue, 11 Nov 2008 08:10:35 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Favor theory, general methods, and the reasons why over rules, frameworks, and how things are done. It is not about how test-driven, or agile, or extreme, or object-oriented, or domain-driven, or feature-driven, or procedural, or [fill in the blank] design and development is done, it is why. Understand why and you can successfully apply the best practices in your own context.

For the life of me I cannot find the source of this. However, years ago a book was written by some CEO who turned a failing corporation around to make it very successful. Years after that the author discovered criticism for his book as the methods he described in his book were not proving successful for other CEOs. In speaking engagements the author would later address the naiveté of people who thought the same things would work for them. Readers failed to understand the why of what the CEO did. The bungling CEOs needed to comprehend the why and then come up with solutions for their own environment, their own context.

Generally speaking...There are at least 3 layers to every application

Joseph Reddy — Mon, 10 Nov 2008 08:10:09 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

At a minimum, implement the most basic 3 layers of code (Presentation, Application, Data Access), even if they are not necessarily tiered. Anything else is muddy and has no place in professional development of the common business application.

Separation of concerns is the most basic axiom of good development. Simple organization like this is the least you can do to help create maintainable code.

Generally speaking...No spaghetti or balls of mud

Joseph Reddy — Thu, 06 Nov 2008 16:12:17 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

No spaghetti, no balls of mud, no permanent hacking

Signs your application might be a plate of spaghetti, ball of mud, or permanent hack…

When you are faced with fixing a subsystem, object, function, or small chunk of code you often feel it would be easier to rewrite it.
When a business rule changes you are not sure where all you have to make the change. This can be a simple as “Let’s make sure all people’s names are displayed like this…” or as serious as “Let’s change all calculations done with dollar amounts to round like this…”
The objects from your “business” layer don’t have any "business" methods
Code routines have little separation of concerns and tend to be large
You routinely have objects with more than 10 properties
You have code that exists a year after you said it was just a temporary fix
You have no layers in your code, no discernable architecture.

Generally speaking...It is not about how fast you can get something done

Joseph Reddy — Thu, 06 Nov 2008 08:26:38 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

It is not about the speed to completion, it is all about understanding and maintaining code which affects the overall speed of the application’s lifecycle. We deliver quickly by delivering little bits at a time with each little bit being well-built, well-tested, and easily changeable. Those bits being objects that like Legos can be used to build and change many different things in our application domain with great ease.

You should be able to check your code in at the end of the day without compilation problems. If you cannot then you are probably not delivering little bits of well-built, well-tested, and easily changeable code.

Know that your application will spend most of its life in maintenance and extension. The first build is only the beginning. Knowing this, build small with quality at every step. The first step to quality is a separation of concerns.

Do not engage in premature optimization or generalization. Worry about speed when it’s actually a problem. Make your code more flexible and generic when that flexibility is required.

Applications should evolve not spontaneously arrive. The metaphor of building an application being like engineering serves us well to a point. However, I cannot go to the mall where an escalator is installed and widen it by two inches to allow wheelchair access, but a change to the width attribute of an object can be done, tested, and released in an hour. In other words, the big design up front required for engineering physical things does not apply to the engineering of software.

Write as much test code as you can that does not require human interaction. This allows you to change and extend things fast and with confidence.

Generally speaking...Practice, practice, practice

Joseph Reddy — Wed, 05 Nov 2008 16:27:08 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

The only thing worse than bad development practices, is no development practices. Developers can debate best practices ad infinitum, ad nauseam. However, even disagreement does not excuse having no practices at all. Although painful, it is worth seeing what a development team can agree on and sticking to as many best practices as possible. Doing this makes working on each others’ code much easier, let alone just understanding it. Furthermore best practices can help new developers avoid mistakes if they follow practices set up by the senior developers.

To avoid pointless disagreement, I have found it works best for a development team to figure out the least common denominator so to speak. The developers need to whittle down the debate to the point of intent and then ignore personal preference. For example, two development teams here quibbled over whether or not variable scope identification should be a prefix or a suffix on a variable. However, that debate was mostly a personal preference debate. What was most important is that both teams recognized the usefulness and elegance of scope identification and did something. They agreed they would not mix and match, but no one would declare a company-wide edict. Everyone is happy.

It is also worth staying mindful of what is personal preference and what truly has benefits and drawbacks. When you encounter something that makes your stomach churn but only because of personal preference, you can hold off speaking up and save your debate-points for something that really matters.

Generally speaking...Write something down

Joseph Reddy — Wed, 05 Nov 2008 08:03:39 -0600

I often find myself in conversations with developers on Experts Exchange, blogs or forums saying, “Generally speaking…blah, blah, blah.” Where blah, blah, blah is replaced by general rules of thumb in regards to development. This is one entry in a simple line of "Generally Speaking..." entries that will provide an easy link for me to point to and of course supplement my poor memory.

As always this is in regards to the common business application.

Generally speaking...

Regardless of how simple the new implementation or change you are about to make is…write something down. At my office, a particular developer is fond of saying, “Someone needs to think it through and write it down.” I couldn’t agree more.

On the smallest level you comment and pseudo code your way through the solution before writing code. Taken a step further you can scratch notes on the back of a napkin or have whiteboard discussions with other developers. But rarely is there a change so insignificant that you don’t at least write down in plain English what you think you are about to do. If you cannot say it in plain English, you cannot code it.

Generally speaking...The best software is never written

Joseph Reddy — Tue, 04 Nov 2008 12:27:11 -0600

The best code (easiest to maintain and has the least amount of bugs) is the code you never write. So you only build the simplest thing that provides value, careful never to add bells and whistles to an unstable code base.

An encapsulation misunderstanding

Joseph Reddy — Tue, 21 Oct 2008 13:36:16 -0500

In a discussion outside of this blog a developer suggested to me that encapsulation was kind of pointless in light of today’s more practiced methodologies. He said that we hide data behind a class so that if the data changed it would not affect anyone using the class. However, because he works on an agile development team with an iterative development cycle that lives and breathes changes, encapsulation was of little concern to him. His application is self-contained at his company so he is aware of all the client code. A simple change to a class’ interface and the compiler will point out all the places affected.

I explained that I too am in an environment where I have control over all clients of the object model so the affects of a simple data change can be easily handled. The encapsulation misunderstanding here is that exposing data is not the problem, or at least not the direct problem. Writing logic against exposed data is what leads to duplicated logic, difficult and incomplete tests, and a fragile design. I have mentioned previously in this blog that at the end of the day my business objects do expose their data, more than would be ideal for sure. The solutions required to prevent exposure are often just not that practical. What is of the utmost importance is that the correct reasons are understood for not abusing the exposed data so any abuse is less likely to happen. The less this is understood and enforced, the more dangerous exposing object data is.

If you are on a team of OO developers very keen to this understanding and code reviews or other practices are in place, then you could expose all your objects’ data without much fear of fragility. On the other hand, if you are surrounded by developers of varying OO-awareness then more ought to be done to hide object data so logic is not accidentally misplaced.

Is the Business Object Dead?

Joseph Reddy — Fri, 17 Oct 2008 08:14:31 -0500

By my estimations (and minor research), most common business applications being written today are in Java, VB.Net and C#. The languages are similar in many respects, not the least of which is that they are all object-oriented languages. I am aware that many if not most business applications written in these languages ignore 40+ years of object theory and proven layered architecture benefits on their way to a lovely big ball of mud.

However, there are legions of developers who do try to tap into the benefits of using an object-oriented design and a layered architecture to produce robust applications that are easy to build, understand, change, and maintain. When they do so they will make a decision as to whether an object representing a business concept will have methods for maintenance-related code or whether it will have methods that handle business logic. Rarely do objects have both as the two needs often lend themselves to different designs.

In the past year or so I have come to the surprising realization that most developers seem to make the methods of their objects maintenance related. The objects tend to be mutable bags of data that act only as a conduit to database tables for moving data in and out, business seems like an afterthought. Frameworks like nHibernate and CSLA promote this kind of design in much the way Microsoft does which is ironic since users of nHibernate and other O/R mapping tools tend to be anti-Microsoft developers.

Gone or least fading is the idea of objects that represent business entities actually having only methods that relate to the business of the object, in other words, they are true business objects. However, I’m not sure how an object-oriented developer whose emphasis is modeling a business in code rationalizes any other kind of design.

Obstacles to The Universal Model

Joseph Reddy — Wed, 24 Sep 2008 19:06:01 -0500

The classic design book from 1988 by Donald Norman, The Design of Everyday Things, is not about designing software, but rather designing any thing that must be used by a person. The author makes the point that a good design is easier to use, easier to learn, and simply better when the thing’s design reflects the user’s view of how the thing works, or in other words: the user’s model. The basic idea is that for any given thing there is the user’s conceptual model and the implementation model. The implementation model is exactly how a thing works or in other words, how it is implemented. Poor design either directly reflects implementation which is often no concern of the user, or the design reflects some model which is not the implementation or user’s model. A door that needs to be pushed designed with a bar that suggests you should pull it is an example that doesn't match either model.

Since software is just another designed thing, the 1995 book About Face was written specifically to address this issue in regards to building applications. Like the authors of many object-oriented books, these authors extol the virtues of building applications that reflect the users’ real-life view of the things involved. Doing this along with reflecting a singular language to describe the real-life views is what Domain-driven design methodologies and the book Domain-Driven Design refer to as creating a ubiquitous language.

When it comes to the common business application I firmly believe that an object-oriented solution based on one model that the stakeholders and developers agree on is the best way to build easily-understood and easily-maintained business applications. I like to refer to that common model as the Universal Model. The universal model is not the user’s model exactly or the implementation model, but rather a model that gestates over time based on the cooperation of stakeholders and developers. The success of that model depends on the cooperation and open-mindedness of both the developers and the stakeholders. Though I have found plenty of literature on how wonderful a combo of OO development, model-driven design, and a universal model is, there is little about just how hard it can be to come up with that model. Here are some of my notes on the obstacles to achieving a good Universal Model:

Obstacle 1: Geeks

Obstacle 2: Players don’t want to play

Obstacle 3: Compromise

Obstacle 4: Abstract Art

Obstacle 5: Experts and Contextual Understanding

Obstacle 1: Geeks

Generally speaking, software developers are geeks who tend to see the world in 0s and 1s. By nature they tend to be interested in how things work and how to make things work. To them the implementation details are the real sexy details of an application (which might explain why many geeks do not care much for user interface development). Putting a universal model on top of their elegant implementation model can feel unnatural and even painful for a geek. The worst is an egotistical stubborn geek who believes that users just need to understand what is really going on because the universal model is the implementation model. The geek sees the implementation model as the only real model because it is true, clean, precise, logical, not-gray, 0s and 1, etc, etc,.

Geeks have to be made aware and then continually reminded who they are writing software for and who decides the success and relevance of their product. Geeks must understand that communication will play a huge part in the success of their development effort and we cannot be hindered by using two different dialects to describe the same system. Geeks can have trouble sticking to the universal model, even when they agree to the concept. Implementation details bleed into discussions, user interfaces, and other public access points [1] to the model. We have to all be vigilant to catch each other “leaking implementation."

Obstacle 2: Players don’t want to play

The software application is the universal model.

The universal model is produced by both the stakeholders and the developers.

Ergo the developers and stakeholders design the software application.

Ideally both parties will agree to this concept and work hard to achieve the universal model. However, often both geeks and stakeholders won’t play along. Stakeholders start tuning out non-playing geeks when they talk of arrays, tables, data source grids, and referential integrity. And then there are stakeholders who are used to the old way of developing software that entails writing up what you want and then getting an application 6 months or more later. Regardless of the poor software they have gotten in the past, these stakeholders are not interested in being active participants in the design of better software.

As with so many software development gotchas, an ounce of prevention is worth a pound of cure. From the beginning stakeholders have to be sold on the idea that they are designing the software by crafting the universal model. When they use terms that are not in the model, the developers should not assume anything and make the stakeholder clarify right there on the spot. Even when the stakeholders don’t play a long, it benefits us to try to figure out their conceptual model so when they speak in business-lingo we have less translation to do. When geeks won’t play along it behooves the team to move them deeper into the code and out of the public access points [1]. This allows them to work blissfully away on implementation code. When a geek that is not playing along speaks up in a meeting it might be worth restating what was said in terms of the universal model to make sure everyone is clear.

Obstacle 3: Compromise

Once upon a time I considered the user model the model that I had to match my design against. I would chastise myself and other developers who tried to introduce new terms into the universal model that did not seem to exist before. For example, when designing a system that managed when documents can be viewed I balked at a new concept called Viewability Specification. I argued that no one says that now or has before, and a user does not need to know about those kind of details. However, the concept did exist before; it had just never been labeled. Having a universal model requires that we label things and agree on how we will refer to these things. On the flip side, I had also been too strict about letting stakeholders use words that did not fit the reality of the design. For example, in a system that processes mass amounts of email, the users referred to the people who were sent emails as recipients. However, the geek in me pointed out that because of delivery problems not every person is truly a recipient of an email. So we used the term Addressee instead. Stupid. No one used that word, everyone continued to call them recipients, and the universal model was rendered pointless.

This compromise also means that stakeholders will have to understand some basic object modeling concepts. In a nutshell they need to understand that every thing in the system ties to an object and an object can figure things out based on what it knows. Some objects' state is stored so it can be used again even after a computer is turned off and back on.

We have to compromise on the model. There are times when developers will have to accept user-speak when it is more abstract than we would like, and users will have to refer to concepts with new terms not used before. Stakeholders and geeks alike can be anxious about the idea of stakeholders speaking in terms of objects, but the concept is so very simple and non technical. The truth is that this can only go so far. Stakeholders might be interested in some of the more gory design details but they will never want (or should have) to grasp the concepts of interfaces, classes, inheritance, or any other gobbledygook. So try as we might, 0% translation between real life and the model is not possible. Do your best, compromise where needed.

Obstacle 4: Abstract Art

Common disagreements in OO design often are in regard to levels of abstraction. What feels perfect for one developer is too abstract or too in depth for another. The universal model sits somewhere among the many levels of abstraction. The discussions about what is part of the universal model and what is deeper implementation is fraught with debatable material. Trying to discern whether a nuance needs to matter to a user can be tough. Most nuances are small, so on an individual basis they are easy to let slip into the model, however they do add up over time and can make the model too complex.

We have to ask ourselves what matters to the public consumer and producers of a concept in our model. Anything that does not matter does not need to be part of the universal model. For example, in the document system mentioned earlier we implemented 2 kinds of documents for various technical reasons. However, when consumed the user does not care what kind of document it is only that it contains information. When produced the administrative user could make changes that technically change it from being one kind of a document to the other, however, the kind did not matter to the user. To them it was just a Document with slightly different attributes. So the universal model only contained the Document even though the implementation behind the scenes had two specialized document objects. This problem can also be solved by putting extra notes in the model for anything that is debated. In the document example there was only a Document in the "index" of the universal model. However, in the fine print there were extra notes added for anyone who cared that explained the 2 specialized docs.

Obstacle 5: Experts and Contextual Understanding

Business experts and developers deep into a model often can give one word 50 different meanings. When their heads are so cleanly wrapped around the problem domain they can get to the point where they don't care what you call the Widget, they know what you mean based on the slightest context. However, there will be those involved in the project, maybe new to the project or a maintenance developer later, that will be confused by the willy nilly use of terms. We have to fight that "don't care" attitude. During design we don't have to dwell too much on it or get hung up on it, but a clean, clear, concise model needs to be a conscious effort of the development team.

[1] Public Access Points of an Application

I use this term to refer to the user interfaces and all public objects and public interfaces of the system. This high-level code benefits from being the most abstract and an exact match of the universal model.