*Words of Wisdom From The Elder

Dave Donaldson posted an article asking if developers should be paid royalties.  He gives an example of a developer who builds a system for a call center that increases sales.  Should the developer get a percentage of the sales as a royalty?  Here’s my words of wisdom on this subject.

As a Developer

It is easy to say, “Yes, pay me a royalty for my work”.  That would be great as a developer but it also wouldn’t be fair since the employer or business if you are consulting has already paid you to perform that service.  The ONLY case where I could see a business agreeing to a royalty is if you the developer built that software for free, and then simply charged a transaction fee.  I equate this to how credit cards work.  American Express takes 3% off the top of all credit card transactions.  That’s 3% of EVERY transaction run through American Express.  Have you ever wondered why not all businesses carry Amex?  Now you know.  It is expensive.  Of course Amex rates are adjusted based on volume but 3% is what business owners have to pay.  They pay that for their customers who want to use the card because they make more sales, thus they don’t mind paying the 3%.  Ask yourself this.  Would you rather have 0% of a profit or 3% less?  The business owner is paying a few to use the credit card system.  Similarly, if a software developer was to create a software program and not charge for it and also not be paid to write the software, then sure, build in a royalty.  I actually know some developers that have done this.

As a Business

As a business owner I would say, “Hell no I’m not paying you a royalty, I already paid you for your services!”.  When a business pays you for your time, you are getting paid to provide a service.  Just because it is technical doesn’t mean a business owner should treat it any different than any other service.  For example, should the company that sent out the mailings for an advertisement get a royalty for their service since they increased sales?  No.  They were paid for a service and that is that. 

We as developers want to put ourselves on a high and mighty post a lot of the time.  At the end of the day the work we do for a business is looked at no different than an electrician who wired the data center.  Should the electrician get paid a royalty as well because the server he is powering took another order from the web site?  The electrician could argue that without him putting in the electricity you could never take that order.  Which is funny because our software can’t even work without electricity!  The electrician trumps us anyway we turn as a developer.  What about the telephone company?  If you are a developer consultant should you pay a royalty to your cell phone provider because you just landed a deal using their phone network?  No!  If we have the mentality of every time we do something we should get paid a royalty on it the only thing that will happen is we will wind up owing someone else a royalty for something else.  It will never end.

Bottom line.  Go to work, provide a service, move on.  If you want to get paid a royalty, don’t charge for your software nor your time.

I have no idea where this post is going to go but I have several things that have come up in discussion lately with developers that I need to get out.  The conversations I’ve been having are around building applications and using the CSLA.Net business object framework.  This article doesn’t focus on CSLA.Net so even if you aren’t using it, these principals still apply.  This post stems from conversations with developers that are spending a lot of time creating beautiful object models.  I’ve seen developers spend a lot of time on perfecting the object model of an application based on sound OOP practices and techniques.  Once the object model is applied to the application it doesn’t work and the developers are scratching their heads asking themselves why.   I’ll explain a common scenario that I’m running into, how to avoid it, and how I think you should think about your object model for your applications.  Definitely fun bathroom reading, so let’s get going!

Throw Away The Object Model In Your Head

As object oriented programming developers on the .Net and or Java platforms we’ve always been taught and trained to think in object models and object graphs.  For example if I asked experienced object oriented programming developers to create an object model for a Veterinary Clinic they would start immediately thinking in terms of physical objects like, dogs, cats, birds, etc.  The reason is because we have been beat to death with OOP principles.  As an exercise I opened up Visual Studio and threw out the very first object model that came to mind based on a Veterinary Clinic.  Here’s what I came up with thinking about the object model from a pure educational standpoint.  I’d kept going but I wanted it to fit onto one screen.

Without knowing anything about the business of a vet clinic and relying only on my experience in owning pets this is the first thing I came up with.  My thought process was vets take care of pets, there are all types of pets, and pets belong to an owner.  Some pets are birds, some are dogs, cats, snakes, lizards, etc.  My college professor would be very proud of my object model I am sure.  He’d feel all warm and fuzzy seeing that I broke down my objects all the way down to dogs then the subclass of spaniels and then cocker spaniels (of which I own three).  On paper this looks great but it is an extremely bad object model.  Don’t do this!  The problem is developers try to apply these perfect object models to their applications.  This is the worst thing a developer can do when building an application.  Well, not the worst, but it sure is a really bad start and a lot of wasted time.

After doing this little exercise I have to admit I felt very dirty.  Seriously.  Why?  Because none of these objects fit into the what the Veterinary Clinic really needs and I honestly just wasted my time proving a point trying to stop you from wasting your time.  Stay with me and I’ll show you. 

A Real Example

I have a friend that is a vet.  After writing this really bad object model down I gave him a call and asked him if he had any software he used to run his clinic.  He said absolutely and he couldn’t run his business without it.  Great, a real world example!

I asked him to tell me about one of the screens they use the most in their application.  He then described what he called the “Account Locator” which after further questioning turned out to be a fancy name for a “Search” screen to lookup clients or accounts in the system.  I took a few mental notes during our conversation and after hanging up made this mock application based on his description. 

The scenario is employees running the main desk at the clinic need to get to accounts quickly and this is why this screen  is used so much.  The scenario is if someone calls the clinic to schedule an appointment, the first thing someone has to do is lookup their account.  The grid below displays some useful information to help the employee find the right account.  It also allows the employee to make the client feel like they are well known.  The example my friend gave is once an account is located the employee immediately knows the pet(s) name, the last time they came in and the type of the pet. 

This scenario now brings me back full circle to the object model I initially built.  Here’s the million dollar question: 

What good is a gigantic object model in this scenario?  Answer:  Nothing! 

The elaborate object model I built out based on my first impression of what objects I’d needed to create are basically useless. 

Why?  For starters, look at where the information from the object model (which shouldn’t have been written in the first place) has to come from just to make this screen work. 

Data is traveling from all sorts of different objects and I didn’t even account for all of the fields.  Are you starting to see why building elaborate object models for an application first doesn’t work?  If you don’t know how the data is going to be used you can’t build an object model. 

This is the main point.  Focus on the business requirements and don’t get all caught up in OOP principles just because it is fun.  And it is fun to be honest.  I love discussing object models but the point is you should be discussing the business requirements!

Do We Really Need An Object Then?

The question I get after showing someone the above example is, “Do we really need an object then since we are just fetching data?”.  When people ask me this what they mean is if they are just searching data and returning data, why all the emphasis on building objects in the first place?

The answer to that is lengthy but I’ll try to hit the high points.  Let’s start with the act of a user entering data into the three fields to search.  This is technically an object.  It is an AccountSearch object.  It isn’t a very hard object to create, it just has three properties.  Here are the things a developer has to think about though.

1. Searching by just pet name will return too many results.  The developer must force that users enter the pet name and the owner last name.
2. If a user enters a phone number only, that is ok.
3. If they enter all three fields that is ok.
4. The phone number must be formatted correctly to match how it is stored in the database.
5. The pet name and the owner last name much match a certain criteria (example % isn’t in anyone’s name).
6. Who is allowed to use this object?  Can just anyone in the world use it?  Probably not.  Therefore there are security concerns as well. 
7. How is the object bound to these fields?
8. Is the object in a broken state (error?).
9. Was the object modified? (in other words you can’t search on something if there is nothing there)
10. Is the object in a valid state?

All of this needs to be thought about and leaving any one of these off can cause lots of problems within the application.  Therefore, this is why we’d have an object that handled all of this logic.  And this is why we call them “business objects”.  In this case it is a single object that encapsulates all of these scenarios.  Take the first letter in the CSLA.Net Business Framework.  The first letter stands for “Component”.  This is where the name comes from because as you can see we are dealing with a single component that accounts for all of this.

How Many Objects Are On This Screen?

Now that we’ve established our initial object model was a complete waste of time, let’s look at what we should do with this example.  Looking at my prototype example, how many business objects do you think are on that example screen?  If you said three, you’d be correct! 

1. AccountSearch.cs – This object encompasses the search functionality I elaborated on previously. 
2. AccountSearchResult.cs – This object is a Read-0nly object that simply holds the data for each row.
3. AccountSearchResultList.cs – This object is a Read-Only-Collection of AccountSearchResult objects. 

Even though the AccountSearchResult object is just a read only object it still needs to be an object.  For example, what if the business required us to change this screen and add another column that only admins could see?  Maybe the column in this case would be a column that held the Owner’s social security number.  In this scenario, the AccountSearchResult object needs to know how to handle this situation and it should know based on the user viewing it that it is not suppose to show that property.  More times than not a developers first reaction is to put this into the UI because it is easy and they aren’t using something like CSLA.Net that provides this functionality out of the box.  Writing that business logic in the user interface doesn’t do any other developer any good if another UI is built like a web UI for example.  Again, that object needs to know how to handle this.  Think component!

What about reusability?

The next question I get after explaining this is:

Are you telling me that every screen the app has, there is a different object?

My answer is any data that is “touching the glass” of the application is encapsulated in some type of object.  In more complex scenarios that may in fact be a full blown object graph with a parent and child objects, etc.  I’m not saying don’t think of any object model but typically more complex object models are what I call core objects to an application.  In this vet application an Owner object would be a core object that would have children of pets, addresses, invoices, bills, follow ups, appointments, etc.  BUT…. ONLY IF THAT IS HOW IT IS VIEWED IN THE APPLICATION!  The difference is you have to think of the YAGNI principle which is if you ain’t gonna need it, don’t put it in your object model.  Build the object model based on the expected behavior. 

Obviously when we build objects we like to re-use them and in some cases you can.  For example why wouldn’t you be able to reuse something like an Address object?  In most cases an address is just an address.  There are cases where even something as simple as an address needs to be in a separate business object though because of the business concerns around it.  For example imagine you were building objects for a realty company.  The address of the client vs the address of the subject property being sold are COMPLETELY different objects with different business rules around them.  This is exactly what I’m talking about.

When building your application you have to think about how an object is used.  For example, take our search screen example above.  What if we were told to build a search screen with the same search fields that returned a slightly different result set.  This is the crossroads where a developer has to really think and make a decision.  Basically there are two choices.

1. Re-use the existing result object and modify it to account for both scenarios.
2. Build a brand new object.

There isn’t a hard and fast answer I can give you as which way you should go.  My default answer is make them different objects since later on you can easily update one without impacting the other as new changes come in.  However you may decide to keep everything in one object based on the amount of time you have.  A general rule of thumb to follow is if 80%-90% of the data and logic in the objects can be re-used, then you may decide to just update the one object.  As you approach a lower percentage of re-use you are just causing yourself problems and need to separate those concerns.

The best way to think about this is let’s say you were building a screen that returned just plain old data (not even thinking objects anymore).  And on that screen you had 5 pieces of data.  Your data query might be something like: 

select col1, col2, col3, col4, col5 from MyTable where col1 like ‘%foo%’

If someone asked you to take out the second column in a certain scenario, would you leave the query alone or rewrite it as:

select col1, col3, col4, col5 from MyTable where col1 like ‘%foo%’

I would HOPE you wouldn’t return the second column if your application didn’t need it!  Building different objects for different purposes is the same thing.  Sometimes you might choose to not modify that query.  But as more columns are changed you’d be crazy not to think about the extra payload you are putting on the database, the network, and latency being built into your application.  It is a fine line to walk but as I said, if I have another screen in my application, I’m going to automatically make another object that encompasses that object for that one given scenario.  Remember, it isn’t just as simple as returning data.  If it were, there wouldn’t be something called business logic!

For further clarification let me say this.  If both objects in my application use the same business logic I am not going to duplicate that logic in each object.  That is silly and doesn’t scale.  That logic should be moved to a common library so it can be referenced from both objects.

Takeaway

The big takeaway from this litany of verbal spillage is when you design applications you have to know how the end-user is going to use the application and what the business requirements are.  Sitting down and building an elaborate object model, while really fun and educational, it is a big waste of time.  Don’t do it.  Sit down and ask questions so the behavior and business requirements can be accounted for.  Whether you are using CSLA.Net or not the same thoughts must go into building the application.  I hope this helps cements these concepts because I know there is a large amount of disconnect with this out there among developers who think everything is a perfect object graph like they learned it in school. 

I’ve said for years that I always wanted to work with people that were passionate about technology.  After countless blog comments, a podcast that will never air, tons of discussions and numerous interviews this week I am changing my mind. 

I’ve said it and have heard others say it.  The word passion comes up a lot in technology.  I went to the dictionary and looked up passion.  Here are the relative points in relation to technology.

PASSION

• intense, driving, or overmastering feeling or conviction
• a strong liking or desire for or devotion to some activity, object, or concept

I am passionate about a lot  of things, for example fishing.  I have a very strong liking or desire for that activity.  I really do.  The problem with using passion to differentiate one person over another is passion is an emotion.  It can’t be measured.  This hit me this week while I was interviewing.  I want someone that has a desire or devotion to technology.  The problem is I can’t measure it, it is an emotion.  Anyone that responds to a question about their passion will provide a really strong argument as to why they think they are passionate.

From this moment forward (or until I change my mind ) I am going to stop looking for passion.  From this point on, I am looking for initiative.

INITIATIVE

• The power or ability to begin or to follow through energetically with a plan or task; enterprise and determination.
• A beginning or introductory step; an opening move

Initiative is key.  One can have all the passion in the world about technology or fishing, but the separating factor between someone that is good or great at either of them is initiative.  At some point that first step has to be taken.  And then another.  And another.  It is the act of doing something of one’s own free will that is the difference.  This I can measure. 

So it is written, so it shall be.

Have you ever watched the movie Forrest Gump?  If you are reading this article the odds are pretty high you have.  As you watched the movie did you notice how Forrest told his story?   Forrest wasn’t the sharpest knife in the drawer but yet he was able to paint a picture that drew the listener in.  He didn’t use big words to speak or even speak in a lavish tone.  Yet his story kept audiences glued to their seats.  It is a true classic.  We can all learn from Forrest, especially software developers.

How To Communicate With Others

Before I dive into a few samples let me just say this.  I am not the world authority on communication.  It is something I have had to do a great deal throughout my life though.  Communication can be done a lot of ways in our society today but no matter what the medium is the same rules apply.

Have you ever had a situation where you met someone that wasn’t in your industry or profession?  Sure you have, we have all done it.  Let’s pretend for a moment you are on an airplane or at a dinner party.  To be friendly you decide to carry on a conversation with a person.  In a typical friendly fashion you ask the person “What do you do?”.  They reply, “I build the CRC47 uplink devices for the SRT1250’s for Yoseph Industries.”

At this point you are thinking to yourself, “What the hell did he just say?”.  Now reverse the role.  What do you tell people when they ask you what you do?  More times than not you’ve probably sounded that very same way to people.  The question of what do you do is a very simple question but the answer people give back more times than not is not the same response Forrest Gump would have given them.  What would Forrest have said in this situation if he worked for Yoseph Industries?  Forrest would have probably said:

“I create these devices that send information up into outer space so folks can watch TV.”

I don’t even have to state the obvious at this point, it is so obvious how much easier it is to understand the Forrest version than the previous one.  As developers and software engineers we have a severe tendency to be the other guy though.  Maybe it is because we like to sound smart, or maybe it is because everything we do is an acronym or skews the English language into something that sounds more complex than it really is.  Whatever the case is, as you go throughout the next several weeks and interact with friends, team members, management, business analyst and so on, listen to what you say and then ask yourself if that is how Forrest would have said it.  If it isn’t, then the chances are you just sounded like the guy at the dinner party you met and no one understands what you are talking about.  Here are some basic tips on how to tell it like Forrest Gump:

1. Do not use industry terms even if it is something as simple to you as a “web service”.  While most all developers know what a web service is, other people don’t.  Gump it down.  Instead of saying “We are going to build a web service in the middle tier”, try “We are going to pull data from that server over to here”.  Leave out the details, model numbers, etc.   
2. If you are communicating something to someone who is not technical, pretend you are talking to your Grandmother or your children.  The visualization of this in the back of the mind will make you speak completely differently so people will understand you better.  A perfect example of this in real life is  when your children ask what does Daddy do.  You immediately think, I have to Forrest Gump what I do down so they can understand it. 
3. Practice.  It takes practice to undo the years of technical speak. 
4. Remember conversation isn’t about you and how smart you are or how smart you sound.  It is about trying to convey your ideas or thoughts so everyone else around you can understand them.
5. Use analogies.  I learned at an early age that analogies go a long ways with people.  It helps them see the overall big picture.  For example, say you are trying to explain to someone why data should be pulled from a web service in TCP binary messages vs XML messages.  Use an analogy.  One you might use is to take a bunch of pieces of paper which simulate the messages and put them into a waste basket.  Then, take the same amount of paper and run it through a shredder to simulate how much more data can fit into the waste basket.  Even the analogy of leaves works as well.
6. Basic rule of communication.  Never ever ever ever use an acronym in conversation until the other person uses it first.

These are six simple steps that if followed will help you communicate more clearly.  If practiced you’ll be amazed at how much more engaging non-technical people will be with you.  Have you thought about how you would handle the initial question of “What do you do” now?  What is it that you REALLY do at work?  The odds are you work for someone and they pay you to help their business run or succeed.  In case you are wondering what my response is when I meet people and they ask me what I do I say:

I tell computers what to do so they can help us run our business.

How To Present Technical Information

This section basically builds off the previous section but it warrants another heading because the challenge of presenting technical information is much more broad.  When presenting technical information, you have to be on your Forrest Gump game more now than any other time.  Unfortunately, a lot of presenters assume since they are presenting a technical session everyone there is technical and on the same page.  If you are presenting at a large conference this is never the case.  If you are presenting something to your immediate team at work maybe so.

A technical presentation is one of the hardest things to pull off.  Why?  Let’s use an analogy (rule #5) to follow my own rules.  It is like explaining Algebra to a room full of students from the 4th grade to the 12th grade.  Sure all of them know some math, but they all know it to varying degrees.  Good presenters poll their audience to know the boundaries of their audience.  “How many of you here have ever done division?  Multiplication?  Complex expressions?  Linear algebra? Algebraic combinatorics?”  Based on the responses, the presenter should raise or lower his Forrest Gump meter and then communicate to the middle of the bell curve (8th grader).  The presenter knows a fourth grader hasn’t done complex expressions but the topic to be covered still has complex expressions in it.  The presenter should realize the forth grader is going to get lost during that section but also should understand there isn’t time to cover the complexity of complex expressions to a forth grader.  A really good presenter will still help the forth grader out by coming up with an analogy so they get the bigger picture.  If the forth grader comes away understanding the bigger picture, the presenter did his or her job.  In order to achieve that though, you have to tell it like Forrest Gump.

So you can understand what I am talking about here is a quick Forrest Gump rendition of Windows Communication Foundation explaining the concept of Service Contracts. 

Windows Communication Foundation is best described as a technology developers using Windows use to let computers and devices talk to one another, no matter what language those devices speak.  One of the ways this is done is by all computers and devices agreeing to at least speak with one another in the same manner.  We call this agreement of how to speak a contract.  No one really signs the contract in legal terms, but everyone that wants to join the party agrees to it.  For example we do this in our daily lives today.  If I were to call a complete stranger there is an understood contract of how we should greet each other and what should be said.  When I call someone they say “Hello”.  I can then say, “Hi, this is Keith, how are you?”.  They will respond, “Fine, and you?”.  Within our conversation there is an agreed upon contract of how we are going to speak. 

Let’s say I am calling a company that provides me services like AT&T or Comcast.  I could say, “Hi, this is Keith, my account number is 123466, how much do I owe on my bill?”.  AT&T and or Comcast understand this type of speak or contract.  But, If I called my Mom and said the same thing, she is going to think I’m crazy.  Thus the contracts that serve these functions given the situation serve different purposes.

While no one really signs these contracts in legal terms, everyone agrees to a verbal contract.  So computers and devices can communicate with each other we put these agreed upon contracts on a centralized computer that serves these contracts up along with the information these contracts return back (how much do I owe would warrant a response of $19.15).  If a device wants to know how much is owed they call the computer with the contract that is able to tell them that information and they get their information back.  Since these agreed upon contracts are really providing a “service” to the computers or devices that use it, we call it a “Service Contract”. 

This is one way to explain the concept of Service Contracts.  I explain this scenario about Service Contracts in Windows Communication Foundation to show you a case in point about how to explain technical things so everyone in the room can understand it.  Hopefully I did a good enough job of that to show you what I mean.  Even if a person has no idea in the end how this really works, they should at least come away with an understanding of the bigger picture because of how it was explained. 

Taking the exact same topic, here is an example of how a presenter explained Service Contracts in Windows Communication Foundation at a Microsoft Tech Ed conference.  I use the example below because I was at this presentation.  Here is how a Microsoft employee explained this same concept of Service Contracts. 

The presenter basically just read the bullet point above and moved on, I remember the presentation in detail because I was thinking to myself that he should have stopped and explained further.  I remember this presentation specifically because when I left the room I had no idea how Windows Communication Foundation worked or even what it was.  It came off as sounding very overly complex and I remember telling someone afterwards, “He talked about all of these contracts and then these litany of bindings.  I think Microsoft just took something simple and made it so overly complex no one is going to use it”.  That was the impression I was left with.  The whole thing just sounded overly complex.  Digging into Windows Communication Foundation in more detail I now know that it isn’t overly complex, in fact it is extremely flexible and has a lot of benefits.  The reason I thought this after the presentation is because the presenter didn’t tell it like Forrest Gump.  They spoke about it from a very entrenched high level abstract view point and then hoped the demos they showed would wow us enough to go look at the technology.  Here’s are some Words of Wisdom from The Elder if you are a presenter:

If your demo is suppose to make everything make sense then you didn’t tell it like Forrest Gump.

I can’t but help think what Forrest would do with the bullet point above.  He would probably rewrite it like this.

Simple, to the point yet easy to remember. 

The next time you are presenting technical information keep all of this in mind.  Once you establish what something is then it is ok to call it a more complex term.  Explain to the person or the listeners that “the thing” you were speaking about is now going to be called “this” from now on.  If you are using slides, this should transition easily.  Also remember the #4 tip above.  The presentation isn’t about you.  You only did your job if you told it like Forrest Gump so they can understand it. 

How To Write Code

Developers write  code.  That’s just what we do.  While Forrest would be a long way from getting hired as a software engineer there are still some things we can learn from him once again.  I was reminded of this the other day as I was reading a post Scott Hanselman wrote about one of the function names in the ASP.Net MVC framework.   In Scott’s article he talked about how he originally referred to it as “Magic”.  Partially it was the name of the function that made it sound magical.  Scott brought this up to the MVC team and after some debate it was renamed.  The fact that the function was renamed is good but even after reading the new name it still isn’t what Forrest Gump would have called it if he was writing that piece of code.  We have a saying in the South that says:

“Call a kettle a kettle.”

A kettle has several names: teakettle, tea pot, tea kettle, or the pot. The point of the saying is to call a kettle a kettle since that is what it is.  There is no need to rename it, obfuscate it, or come up with a name that sounds cool or anything like that.  Just call it what it is.  For those that aren’t well versed in kettles, a kettle has a spout and a lid.  Just because it can be used to boil tea doesn’t mean it gets a new name.  Just call it what it is, a kettle.

I was reminded of this as I read Scott’s post.  Here is what the original name was.

After some discussion with the team it got renamed to:

The Forrest Gump version of what is happening at this point is data is getting submitted from a form and a developer has an existing object he or she wants to take the data that is getting posted from the form and map it to their object.  Now ask yourself, even if you don’t understand the full scope of what is going on at this point.  What would you call it?  And then ask yourself what would Forrest call it so the lady sitting next to him on the bench in the movie could understand it?  Would she have understood either of the two previous examples?  The answer is probably not.  While the second example is less ambiguous than the first one, it still doesn’t tell the story like Forrest Gump.  Why do we care?  Answer:  What we name our functions and variables communicates what it does back to other developers that use it.  It boils down to communication.  The easier it is to read and understand the easier it is for developers to pick up on, even if they don’t know what’s going on. 

It isn’t my place to tell the MVC team what they should call this method but I know that I would not “stumble” upon the new name as Scott mentions in the article.  It isn’t Gump and doesn’t call the kettle a kettle, at least that is my opinion.  I think it is calling a kettle a tea pot.  It wouldn’t jump out at me merely by reading the API as to how or what that function did.  Phil Haack, one of the developers on the project posted a comment with a new name that was pretty funny.  While Phil’s comment was sarcastic, you know what, at least it tells it like Forrest.  Here is what Phil posted:

Obviously Phil was making a sarcastic comment, but you know what, that is closer to what it should be called!

The whole point is when writing code, tell it like Forrest Gump and call a kettle a kettle.  Don’t obfuscate your code with naming conventions or terms that don’t make sense.  Things that should be simple, well, should be simple.  They should be easy to find and simple to understand.  For some reason though when a developer touches a keyboard and starts writing code they talk themselves into calling things something they aren’t.  There are countless examples within frameworks and systems that aren’t simple to understand.

Let’s take a case in point within the .Net framework.  Let’s say I wanted to write some text to a file that I already had in a string variable.  Since this is an IO operation I would probably expect to be able to “stumble upon” how to do this within the System.IO namespace.  As I type System.IO I see there is a File sub namespace.  So far so good.  This makes sense since one of the things we do with IO is handle files.  As I stumble around trying to find which method to use I see Create() and CreateText().  Since I have some string data, and a path where I want this file to be written to nothing jumps out at me.  Thinking like Forrest Gump I’m looking for something like this to help me out:

Simple, easy to use and I would be on my way to my next business problem.  Yet, if you look at the .Net framework and see how the CreatText() method is used, it isn’t Gump.  It takes further reading and backward thought to understand that the words CreateText actually mean to either create or to open.  Here is the official documentation from MSDN.

Now ask yourself, is this calling a kettle a kettle?  Is it what Forrest would have named it?  The answer to both is no.  Not only does the name of the method fly in the face of what it actually does it is way more complex to write a file to the file system with the framework than it should be.  Here is full example.

// Create a file to write to.
using (StreamWriter sw = File.CreateText(path))
{
    sw.WriteLine("Hello");
    sw.WriteLine("And");
    sw.WriteLine("Welcome");
}

Are you starting to see the point?  This is a real easy problem to fix and one that should be fixed. 

Try this the next time you finish a new feature in an application.  After you get done with your code ask yourself, if my Mom read this would she know what it was doing?  If your answer is no, then developers on your team are going to also have a hard time.  One scenario that plays out because code is not written like Forrest Gump is when a particular engineer works on a feature in a system by themselves.  Down the road that feature needs to be enhanced or fixed and the original engineer that worked on it is on vacation.  The engineer assigned to it reviews it and says:

“You better wait on (insert name) to get back.  I don’t know how it works, I looked at it but don’t understand it.” 

I’ve seen this more times than I care to count and have even said it myself.  Writing applications doesn’t have to look like rocket science yet more times than not developers love to make things harder than they really need to be.  Software should tell a story as it is read by other developers.  If it does then other developers will love working on the system.  If it doesn’t, they will hate it and eventually rewrite it. 

We’ve looked at a lot of ways developers can learn from Forrest.  Forrest was a simple man but he had a great way of explaining a complex story about his life in a way that everyone could easily understand.  If you try these techniques don’t think just because you are explaining or writing something the way Forrest would that you are dumbing yourself down.  You’ll actually find it harder than you think!  The next time you are in a meeting, giving a presentation or writing code just ask yourself one question.

Did I just tell it like Forrest Gump?

It never ceases to amaze me how different naming conventions are from language to language.  It seems each language has their own coding convention or style that gets adopted over time.  More times than not these naming conventions are established by authors in books, magazines, and Internet articles.  Developers that read those publications follow suite the majority of the time.  For example, I can remember years ago developers who wrote PHP named files they included in their programs with the extension of “.inc” yet other files ended in “.php”.  The huge downside to this was the .inc files would be passed directly through from an Apache server as plain text file instead of getting parsed as code.  This would allow want to be hackers to see the code to a web site.  The worse part is a lot of the time the database username and password was visible in plain text.  Why was this done?  It was done because Rasmus (the guy who wrote PHP) put it in his samples.  Once it was printed, it became a standard that took many years to correct.

After programming in a language for several years one tends to adopt a certain style and I am no exception to that.  It is funny how caught up we get in how things are named.  Our brains work on consistency though.  If I have to read code someone else wrote that doesn’t follow my naming conventions and style I am now out of my comfort zone and have to do double translation.  First translate their code into what I would have done to understand the problem better, and then read their code and translate that into what it is doing.  The worst examples of this are when you have to read code in a language written by a developer who is new to the language that brings in the previous style of the language they’ve used for years.  It is painful to read code that isn’t written in the “implied” standard the language is written in.  By implied I mean if you look at Intellisense for .Net objects, enumerations, namespaces, methods and so on you’ll quickly realize that everything starts with a capital letter.  A developer learning a programming language from scratch will pickup on this and more than likely follow this implied naming convention.  However, if a Java or PHP/Perl/Bash/Ruby programmer writes .Net code he or she will more than likely write code the same way they did in the Java world.  Example:

Typical .Net Version

        public int AddTwoNumbers(int x, int y)
        {
            return x + y;
        }

Typical Java Version

        public int addTwoNumbers(int x, int y)
        {
            return x + y;
        }

Typical Scripting Language Version

        public int add_two_numbers(int x, int y)
        {
            return x + y;
        }

Three distinct ways to name a method.  The difference in the first two is the upper / lower casing of the method but it is more obvious with the third example in how different platforms write their code.  I’ve had the pleasure, I mean pain of reading .Net code written or translated by developers who are new to .Net.  I can tell within a few lines the language the person translated the code from or the language they wrote in previously.  Assuming they don’t “change” how they write their code.  I suspect most others can as well.

When developers transition to .Net or learn .Net it amazes me how many of them deviate from the implied naming conventions.  For example, all namespaces in .Net are Pascal case with no underscores yet I see developers coming from a Java background creating namespaces like “com.something.foo” and breaking this convention instead of following what has been established before they got there.  I find the .Net framework very consistent in how it is written and coded.  If you are learning .Net the best rule you can follow is first follow the implied naming conventions.

I like standards, especially when moving developers in and out of development teams.  It amazes me when I look at a problem that isn’t formatted or named the way I prefer, how much longer it takes me to understand what the developer is doing.  This can be from how curly braces are structured, to variable naming conventions and much more.  I have had situations that before I could help the person I had to refactor their code before I could understand it.   More times than not while I am refactoring the person will find their own mistake because of how I refactored it (simplicity is genius).  Naming conventions are good because it helps others to quickly understand what is going on.  Again I go back to my point that if someone writes in a style you don’t follow you are doing double the work to understand it. 

Here’s an example of the subtlety in the naming of variables that can be confusing.  For example if I see a property of an object called “AddressCollection” I know immediately this is a generic list of Address objects.  Easy, Forrest Gump, no questions asked. Conversely, if I see “Addresses” as a property I have no idea what this is.  It could be a collection or just an object.  I’ve taught many a programming class and I’ve seen a lot of code written by complete newbie programmers.  It always amazed me at how I could write code they couldn’t understand just by changing my “style” or naming conventions.  Folks, this stuff does matter and especially in larger team environments.    If you don’t believe me, then write a program with variables named after Flintstone characters and then give it to a Senior Engineer and see how long it takes them to figure out what it does versus one that isn’t.

There are a lot of preferences when you talk to developers about how they code.  I personally like what makes sense and is as Gump as I can get it.  I also like to follow suit of how other things are named to provide consistency.  So what are my preferences?  Well, I won’t go into each and everyone but here are a few of my stronger opinions.

Variable Prefixes
A controversial topic no doubt but I prefix all private variables with an underscore.  I do this because it is easier to read.  It is also one character different which follows the rule of not making private variables and public variables different by case.  Example:

        private string _propertyName;
        public string PropertyName
        {
            get { return _propertyName; }
            set { _propertyName = value; }
        }

I’ve seen a lot of code written and published on the Internet that prefixes variables with “m_”.  Most of the time this is due to legacy habits.  For those that do this, please stop, you aren’t coding in VB6 anymore.   It boils down to simplicity.  I use one character, it avoids naming collisions and is easy on the eyes to read and less distracting. 

I also have seen code where developers will prefix a variable with a shortcut of a type.  For example if they are creating an array they’ll do arrMyVariable or if the variable is a string they will do strMyVariable.  Usually when I see this type of code it tells me the person came from a scripting language background whereby variables can literally be different types in the next statement.  For example this is something we used to do in Perl whereby this would help other developers to know what was in the variable or suppose to be in the variable so they wouldn’t try to change the type. 

Curly Braces
Another controversial topic is curly braces.  I line curly braces up on top of each other (each gets their own line).  Some may not agree with this but I find it extremely easy to debug sections since the braces line up and allow the eyes to see blocks of code quicker.  When you get into nested situations it is easier to see the “blocks”.  For those that don’t agree I have tested this in many programming classes I’ve taught and students who are “learning” a language from scratch will agree 100% of the time that lining them up is easier.  Here’s what I’m talking about with some random code that makes no sense and isn’t suppose to.  Two versions of it with a lot of nested blocks.

HARD TO READ

        private void MyFunction(int x) {
            if (x % 2 == 0) {
                for (int i = 0; i < x; i++) {
                    if (i % 2 == 0) {
                        // do something
                    }
                    else {
                        // do something
                        for (int i = 0; i < x*i; i++) {
                            // something else
                            if (DateTime.Today.DayOfWeek == DayOfWeek.Saturday) {
                                Console.WriteLine("Take the day off.");
                            }
                        }
                    }
                }
            }
        }

EASIER TO READ

   private void MyFunction(int x)
        {
            if (x % 2 == 0)
            {
                for (int i = 0; i < x; i++)
                {
                    if (i % 2 == 0)
                    {
                        // do something
                    }
                    else
                    {
                        // do something
                        for (int i = 0; i < x*i; i++)
                        {
                            // something else
                            if (DateTime.Today.DayOfWeek == DayOfWeek.Saturday)
                            {
                                Console.WriteLine("Take the day off.");
                            }
                        }
                    }
                }
            }
        }

While the second example is longer in terms of lines of code (this is why God created regions) one thing you can see easily is how nested it is and how the code breathes more.  The first approach looks like it is cramming the code together.  Like I’ve said, I have tested this in every programming class I’ve taught and the consensus is the second example is always preferred and easier to understand.  The nice thing is for those using Visual Studio this is the out of the box behavior. 

If Statements
A pet peeve of mine is when developers shortcut if blocks.  Here is what I mean.

If Block Shortcut

    public Foo(int x)
    {
        if (x % 2 == 0) Console.WriteLine(x.ToString() + " is even");
    }

If you have a single line for an If block you can shortcut it and leave off the curly braces.  It is a feature, yeah.  Some other languages support this and C# does as well.  Personally I can’t stand this because of several reasons.  One, debugging.  If I want to set a break point just when the Console.WriteLine is hit I can’t.  I have set it on the one line and check it each time.  Another reason this disturbs me is if the business logic changes where I have to print an else statement it has to be reformatted anyway.  Go ahead and add the curly braces up front instead of waiting.  The third reason is when looking at the code there may be things that occur after this and it is confusing to read to know what the intent of the person that originally wrote it was.   This also ties into the readability of the code as outlined in the curly braces section.   Bottom line, don’t shortcut just because you can.

Namespaces
I mentioned this earlier but I’ll mention it again. Namespaces should be Pascal Case.  A namespace should be something that is agreed on BEFORE you write code for a project.  The standard is to use the CompanyName[.Team][.SubTeam] + Project + [.Feature][.Design].  Example:  Microsoft.Practices.EnterpriseLibrary.Caching.  Of course you can leave off the team, subteam, feature or design if you choose depending on how global the project is.  Don’t worry if you do that.  ScottGu isn’t going to show up at your doorstep asking you to change it.  There aren’t any hard and fast rules these are just the “implied what Microsoft does” rules.  For more detailed information Microsoft has a reference page about namespaces available on MSDN.

Naming Preferences
This is a large topic, or can be.  So instead of re-hashing this on my own go read Peter Brown’s article on naming conventions.  It is fantastic. This is one of the few articles that I can say I agree with 96.78582762% or more of what it states.  I imagine if I read Peter’s code it would look exactly like mine in terms of naming preferences.  Beyond Peter’s article there is also naming guidelines already established on MSDN that outline how to name classes, enumerations, parameters, properties, events, and so on.  If you are wondering what I do, for the most part I follow that guideline.