Peter Ritchie's MVP Blog : Software Development Practices

Evolving code over time

PeterRitchie — Tue, 31 Mar 2009 04:02:00 GMT

Given economics, time constraints, resource limitations, etc.; you can't write all the functionality for a given solution for a single release. Even if you weren't limited by these constraints, you're likely to get changing requirements as development progresses and everyone learns more about the software under development.

It's fairly easy to prioritize what is developed and what isn't. You simply develop only what you need (see YAGNI). But, how do you manage adding new functionality without causing undue grief? One way is to only make additive changes to the code. For example, let's say we have the method create CreateRequestPacket that creates a blob of bytes to send to a host over the wire:

public static byte[] CreateRequestPacket()
{
    byte[] result = new byte[12];
    result[0] = REQUEST_CODE;
    result[1] = NO_OPTIONAL_DATA_FLAG;
    result[2] = (byte) (result.Length - 2);

    Random random = new Random();
    for(int i = 3; i < result.Length; ++i)
    {
        result = (byte) (random.Next() % byte.MaxValue);
    }
    return result;
}

In iteration x it writes out a request making certain assumptions about what the request contains. But, in iteration y it needs to optionally include other data. A non additive way is to simply modify CreateRequestPacket to do what is needed:

public static byte[] CreateRequestPacket(bool useOptionalData)
{
    byte[] result = new byte[12];
    result[0] = REQUEST_CODE;
    result[1] = OPTIONAL_DATA_FLAG;
    int index = 2;
    if(useOptionalData)
    {
        result[index] = GetOptionalData();
        ++index;
    }
    result[index] = (byte) (result.Length - index);

    Random random = new Random();
    for(int i = index + 1; i < result.Length; ++i)
    {
        result = (byte) (random.Next() % byte.MaxValue);
    }
    return result;
}

Now all calls to CreateRequestPacket need to change before a build can occure and you might not be able to modify all the files that contain these calls. So it causes undue blocking and forces you to change a number of files before you can check the file that CreateRequestPacket is contained withing.

Another way of implementing this would be to implement an additive change. That is, add a method that does what is needed and change the previous implementation to call the new method. For example:

public static byte[] CreateRequestPacket(bool useOptionalData)
{
    byte[] result = new byte[12];
    result[0] = REQUEST_CODE;
    result[1] = OPTIONAL_DATA_FLAG;
    int index = 2;
    if(useOptionalData)
    {
        result[index] = GetOptionalData();
        ++index;
    }
    result[index] = (byte) (result.Length - index);

    Random random = new Random();
    for(int i = index + 1; i < result.Length; ++i)
    {
        result = (byte) (random.Next() % byte.MaxValue);
    }
    return result;
}

public static byte[] CreateRequestPacket()
{
    return CreateRequestPacket(false);
}

This allows you to check the file that contains CreateRequestPacket in right after passing unit testing and allows you to gradually change all calls to CreateRequestPacket as time permits.

DevTeach 2009 Vancouver

PeterRitchie — Thu, 26 Mar 2009 16:33:00 GMT

The schedule for DevTeach 2009 Vancouver has been announced (http://www.devteach.com/). There’s lots of great software development sessions from some of the leaders in our industry.

If you’re planning on improving yourself, this is the conference to go to. Not only can you attend excellent sessions; but you can hob-knob with the presenters and pick their brains.

If you have a friend or co-worker who’s interested, there’s a limited-time two-for-one offer for an even better price: http://www.devteach.com/Register.aspx

Developing with Source Code Control - Best Practices Part 2

PeterRitchie — Wed, 11 Mar 2009 14:36:00 GMT

[Edited 14-Mar-09: clarified generated code SCC practice]

This edition provides SCC vocabulary and some more practices that make development life easier.

Vocabulary
Trunk
The root of the project or database. Sometimes called mainline or baseline; depending on the SCC structure, this is where most of the development occurs.
Mainline
The root of the project or database. Sometimes called trunk or baseline; depending on the SCC structure, this is where most of the development occurs.
Baseline
The root of the project or database. Sometimes called mainline or trunk; depending on the SCC structure, this is where most of the development occurs.
Tag
A snapshot in time of the system or a project/subfolder in the system. Usually also associated with an annotation explaining the significance of that point of time. Also known as label.
Label
A snapshot in time of the system or a project/subfolder in the system. Usually also associated with an annotation explaining the significance of that point of time. Also known as tag.
Branch
A "copy" of subfolders and files that are controlled separately from the trunk with an intention to eventually merge back into the trunk.
Merge
Unifies two independant changes into one. Often the process of merging requires manual resolution of conflicts.
Merge Conflict
When two independant changes cannot be automatically merged.
Commit
Same as check in
Check in
When changes are written to the repository.
Head
The most recent version of code in the system.
Fork
For the most part, same as branch--depending on the SCC system. More fun to use than branch, "I forked the code".
Copy-modify-merge
Under this SCC model the SCC always merges changes back into the database (trunk or branch, depending on what you're editing). This model assumes a team model where there is the likely posibility of more than one person working on the same file at the same time. This model rarely precludes the ability to lock a file before modification if changes to the file cannot be merged). This is the preferred SCC model.
Lock-modify-unlock
Under this SCC model the SCC forces devs to lock files they wish to edit before modifying them. (with IDE integration this is often transparent).
ALM
Application lifecycle management.

Practices
Don't use Visual SourceSafe for your SCC system.
Believe me, I've been there and have the scars to prove it. Visual SourceSafe (VSS) has a unique process that isn't mirrored by many major contemporary SCC systems. VSS is a distributed file-based SCC system and as such is prone to data corruption--not really something that is acceptable in any sort of "Control" system. Branching is really difficult in VSS. If you're one person and you have your VSS database on the same computer; you're likely fine. Otherwise, do yourself a huge favour and consider another SCC system, like Subversion (it's free). VSS doesn't scale well; as time goes on and the database increases in size, developers are added to the project, VSS gets slower and slower.

Don't put generated code in SCC
SCC provides the ability to rollback to a state in the past that allows compilation of the solution. Code that is generated [edit start] as part of the/a build process [edit end] can be generated at any time; there's no need to put that code into SCC. With lock-modify-unlock SCC systems, generated code that is checked-in will be locked and cause errors during build unless you lock it on every build. This will cause conflicts in lock-modify-unlock systems in that you end up not being able to build while somone else is building (yes, you likely build serveral times a day).

Make sure unit tests pass before checking in.
This means *all* unit tests. If you check in a change that causes a unit test to fail, someone else won't know where to start to make that unit test pass. You're wasting your time and setting the project schedule back by not ensuring unit tests pass before checking in changes. If your team allows it, use some sort of continuous integration suite. This allows you to get feedback upon every check-in that tells you whether all the unit tests pass. If you have an SCC or ALM that supports it, enable guards that force the unit tests to pass before changes are allowed into SCC.

Work on one set of related changes at a time.
It's more efficient to work on one thing at a time. Switching back and forth from task to task means wasting time getting into a different frame of mind and sometimes a different configuration. This also causes issues with SCC in that you've now got modified files that you're not currently working on. The longer they're kept unmerged, the more likely there will be issues during merge (someone else made a changed that conflicts with yours, and if everyone else is checking in often, you're the one that has to deal with all the conflicts). The more things you're working on at once, the more likely that one set of changes becomes dependant on another and you simply can't check your files in until all the changes you're working on are complete. Work on one set of related changes at a time and check those changes in to avoid not merging your changes often.

Check-in often.
SCC provides developers the ability to keep a history of their changes. But, this only works if you check your changes into the SCC system. When you have something that compiles, check it in. The more often you check changes into the SCC system the less likely you'll get into a situation where you have to deal with merge conflicts. The more often you check changes into the SCC system the least complex the changes will be. If the changes are not complex and you do run into a merge conflict, the less work will be involved in resolving the conflict. Do your sanity (and the sanity of your team mates) a favour and check in often. See next practice.

Avoid leaving changes overnight.
Check in your working changes before you leave for the day. If it compiles and works (unit tests pass) there's likely no harm to checking in. Leaving work for an extended period of time means it's that much harder to get back into that mindset; if you check in and describe the check in, you now have a history of the day's changes with an annotation making it easier to get back in that mindset. But, since you've checked the files in, you may not need to get back into that mindset (if you didn't check in, you *must* get back in that mindset in order to check in).

Never destroy SCC content.
SCC offers the ability to get back to a project state at any time in the past. If you destroy content from the system, this incapacitates this ability. It goes against keeping any sort of history of a project to destroy content, so don't do it unless you intend never to make use of the history for that project (i.e. you're destroying and entire project and you never intend to work on it again or support it).

Don't Bypass Copy-modify-Merge
Eventually you'll be in a situation where you need to edit a file at the same time as another person. In this case you'll need to merge your changes. The copy-modify-merge model accepts this inevitable fact and makes merging a first-class citizen of your development process; not some nebulous process that occurs only occaisionally. With a properly designed system the need to merge should be minimized. I've seen teams instigate a policy that you must lock the file before you modify it. I've also seen teams configure a SCC provider to automatically lock a file when changes are made to it. This is the wrong thing to do on software development teams. It leads to one of two things: 1) people just stop working when they can't lock the file they need to edit; or 2) they end up forcing copy-modify-merge that isn't supported by the tools they're using, which often leads to human errors and errors in merging.

I hope to continue this series as time goes on, if you have suggested topics, please comment. I expect to keep pretty generic; but could get SCC-system-specific, if there's interest.

A Upcoming Pandemic of Domain Anaemia

PeterRitchie — Thu, 29 Jan 2009 17:10:00 GMT

There's a well-known anti-pattern called the anaemic domain model[1][2]. This anti-pattern basically says domain entities, chronically, have little or no behaviour (remember, object-oriented design is about attributes and behaviour).

It should be obvious that a domain model that isn't truly object oriented is a domain model with a problem. But, let's look at other reasons why the Anaemic Domain Model is an anti-pattern. Your Domain is the nexus, the essence, of your system.

An anaemic domain model is basically a reporting system. Each "Entity" becomes, essentially, a query. This is fine, reporting systems are necessary and prevalent. But, to shoe-horn a domain model on top of this leads away from good reporting patterns that could add value and increases complexity, needlessly. The designers spend most of their time trying to force entities on the system, without recognizing the basic reporting nature of the system. This usually leads to "reports" that have to pull in multiple domain "entities" to generate the report--rehydringing data into an entity (usually through some sort of ORM) with no value added. i.e. an ORM that will manage the child-parent relationship (and either pre-load or lazy-load aggregates) doesn't provide much value here.

The worst case scenario with an anaemic domain model is that there really is behaviour there; but it's not handled in the domain entities; it's handled in a different layer. This is a problem because this circumvents the whole point of a domain model and layering.

One indication of anaemia is that most of the domain classes simply contain attributes. Anyone familiar with patterns should recognize this as a Data Transfer Object, not a Domain Entity. There's nothing wrong with DTOs, they're very important in almost all systems with any sort of complexity; but they're not Domain Entities. Let's be truthful, there are systems with little or no behaviour in the domain; and that's not a bad thing. Systems like this likely don't need a Domain Model and may not need techniques like Domain Driven Design. The quicker people recognize that, the quicker they can be using a more appropriate architecture and design. In some extreme cases the anaemic-domain-entity-DTOs service other DTOs

Now, where am I going with this? Well, there's been a series of guidance out of Microsoft Patterns and Practice about some application "patterns".

First, let me describe what a pattern is. A pattern is a way of "documenting a solution to a design problem" [3]. First, for it to be a pattern, it needs to detail the problem and it's context, then provide a solution. The latest "patterns" from P&P do not detail the problem or a context. They're simply architectural descriptions.

Now the association between the Anaemic Domain Model and the latest P&P guidance. In 3 of the 5 recently publish "patterns" the following is detail is included: "A Domain Entity pattern is used to define business entities that contain data only." This is the very definition of an Anaemic Domain Model. Plus, in the RIA pattern the following, contradictory, detail is included: "Domain entities are responsible for implementing business rules. Entities from the domain model represent business objects that contain data and implement behavior [sic]. In other words, the business objects are responsible for implementing business operations and interacting with other business objects."

This is disconcerting because historically sample code and guidance from Microsoft is simply reused without thought. This leads to poorly designed and architected applications, and the .NET community as a whole is seen as one that produces poor-quality code and design. Without context about the problems these patterns try to solve, they will be misused—likely forced upon contexts and situations where they don’t fit, simply because “they’re from Microsoft”.

[1] MF Bliki- AnemicDomainModel

[2] Anemic Domain Model - Wikipedia, the free encyclopedia

[3] Design pattern (computer science) - Wikipedia, the free encyclopedia

Technorati Tags: Microsoft Patterns and Practicies,Anti-patterns,Anaemic,Anemic,Domain Model,Microsoft

del.icio.us Tags: Microsoft Patterns and Practicies,Anti-patterns,Anaemic,Anemic,Domain Model

Developing with Source Code Control Best Practices Part 1

PeterRitchie — Sat, 18 Oct 2008 13:54:00 GMT

This post will detail some first principles about source code control (SCC) and provide what I consider the most basic of practices that every dev should follow.

What is SCC?
SCC provides developers the ability to keep a history of their changes. SCC allows developers the ability to group file changes together with an annotation. SCC allows developers the ability to get back to the state the project was in at any given point in time, arbitrary or specific (Beta 1, RTM, etc.). SCC provides development teams the ability to more easily work on the same files at the same time. SCC allows developers to see who did what, when, and usually why. SCC allows development on more than one branch of the code at a time. Depending on the SCC, SCC allows developers to link changes to tasks, work items, etc.

Basic practices
Never check in changes that cannot be built.
This is pretty self-explanatory. Referring back to what is SCC: "SCC allows developers the ability to get back to the state the project was in at any given point in time". This means anyone can get back to a state where the project won't build if you check in changes that cannot be built. This causes undue friction at points temporally distant from the changes--which means there lots of work (time) involved to find and implement a solution (e.g. is the state 5 seconds before better, is the state 5 seconds after better, etc? All things that need to be researched and tested before continuing--wasting time and resources).

Check in related changes atomically.
This builds on the first practice, if all related changes are checked in as a unit the likelihood of that check-in breaking the build is highly improbable. Atomically means all related changes are checked in at the same time. With most SCC systems this is extremely simple, and usually means selecting all the files you have edited (or all the subfolders you have modified folders in--or the one subfolder if you have unrelated changes, see part 2). This might mean avoiding SCC IDE integration if your changes span several solutions. If you can't check in changes atomically (really question this if you think you can't. If you honestly can't, I'd suggest changing SCC systems) order the check ins to avoid build problems. For example, if you added an enum to somefile.cs, then used that new enum in someotherfile.cs, check-in somefile.cs before checking-in someotherfile.cs. Checking in somefile.cs first will not put the source code in a state where it cannot be compiled. You're working on a team, anyone on the team can get the state of the project at any time, like between non-atomic file check ins. This means they get code that doesn't compile and they won't know why or how to fix it--blocking them from doing their work and wasting time and impacting the project schedule.

Make use of shelving.
If what you've coded needs to be given to someone else to get the source code to build properly, don't check it in in order to give it to that other person. On cases like this, if your SCC has shelving or shelvsets, shelve the changes and inform the other person of the shelvset instead of checking in. Let them check in the working changes as an atomic unit. If shelving isn’t an option (consider or petition for an SCC system that does, then), send them the files for them to check in after modifications. See next practice.

Get all current code and build before checking in.
Someone may have made changes between when you got the code you working on and when you want to check in. If you don't get the latest code (and potentially merge it with yours), what you check-in may leave the controlled code in a state where it cannot be built. Get all the current code to make sure you have what will be the state of the code when you check in and that it builds first. If your build process is long, this may require several tries. You should address build times if this is a common problem. Communicate to the rest of the team that you need to check in changes and that they hold off on checking in related components if necessary.