Ruthlessly Helpful

Stephen Ritchie's offerings of ruthlessly helpful software engineering practices.

Category Archives: Opinion

First, the mental creation

With physical things, like buildings and devices, etc. people seem to be generally okay with generating strong specifications, such as blueprints, CAD drawings, etc. These specifications are often about trying to perfect the mental creation before the physical creation gets started. In these cases, the physical thing you’re making is not at all abstract, and it could be very expensive to make. It’s hard to iterate when you’re building a bridge that’s going to be part of an interstate roadway.


What I’ve seen in the world of software, the physical creation seems abstract, and engineers writing software appears inexpensive when compared to things like steel and concrete. Many people seem to want to skip the mental creation step, and they ask that the engineers jump right into coding the thing up.

If the increment of the thing that your team is to write software for is ready to be worked on, and you have a roadmap, then an iterative and incremental approach will probably work. In fact, the idea that complex problems require iterative solutions underpins the values and principles described in the Manifesto for Agile Software Development. The Scrum process framework describes this as product increments and iterations.

However, all too often it’s a random walk guided by ambiguous language (either written or spoken) that leads to software that lacks clarity, consistency, and correctness.

Sadly and all too often, the quality assurance folks are given little time to discover and describe the issues, let alone the time to verify that the issues are resolved. During these review sessions, engineers pull out their evidence that the software is working as intended. They have a photo of a whiteboard showing some hand-wavy financial formulas. They demonstrate that they’re getting the right answer with the math-could-not-be-easier example: a loan that has a principal of $12,000.00, a term of 360 payments, an annual interest rate of 12%, and, of course, don’t forget that there are 12 months in a year. And through anomalous coincident, the software works correctly using that example. Hilarity ensues!


Unfortunately, QA is often squeezed. They are over-challenged and under-supported. They are given an absurd goal, and they persevere despite grave doubts about whether a quality release is achievable. Their hopelessness comes from knowing that the team is about to inflict this software on real people, good people, and the QA team doesn’t have the time or the power to stop the release.


What are the key things to take away:

  • When the physical creation of software seems to be cheap, comparable to the mental creation of writing down and agreeing to light-weight requirements, then the temptation exists to hire nothing but software engineers and to maximize the number of people who “just write code”. In the long run, however, the rework costs are often extremely expensive.
  • In the end, the end-users are going to find any defects.
  • Better to have QA independently verify and validate that the software works as intended, of course, what is intended needs to be written down:  clearly, consistently and correctly.
  • QA ought to find issues that can to be resolved before the users get the software — issue reports that show clear gaps in required behavior.
  • QA conversations with engineers ought never degenerate into a difference of opinion, which happens when there are no facts about the required behavior. Very often these discussions (rhymes with concussion) escalate into a difference of values — “you don’t understand modern software development”.

Interestingly, the software’s users are going to find the most important defects. The users are the ultimate independent validators and verifiers. End-users, their bosses, and the buyer can be ruthless reporters of defects. In fact, they might very well reject the product.


We are the Pakleds; You *are* smart!

As one of the weary consultants on a multi-year software development project for a major lending institution I observed what became known as the “Pakled-Customer Syndrome”. The Pakleds are a race of dimwitted aliens from Star Trek: The Next Generation (TNG), which are first seen in the “Samaritan Snare” episode (summary here). They co-opt the technology of other spaceships through manipulation, brainless praise and hostage taking. Responding in good faith to the Pakled distress call the Enterprise is ensnared by the Pakled’s intractable problems and pig-headed attitude.

In the TNG episode, the Pakled are characterized by the repeating of a few simple phrases. When the crew attempts to engage them in a dialog about their distress (e.g. Is your ship damaged?) the response is always; “Uh-hunh.” Diagnostic inquiry and problem-solving are met with; “It is broken…. Can you make our ship go?”, “Make our ship go”, “Will our ship go now?” Any perceived progress is met with oddly enthusiastic and sycophantic praise; “He is smart”, “You are brilliant”; but this turns out to be unproductive support and belies their hidden agendas.

On many projects the customer can be entrenched in their own Pakled-mindset and the project is soon mired in the resulting quicksand. As organizational behavioral dysfunctions, here is what characterizes the “Pakled-Customer Syndrome”:

  • Snare one: The customer takes no responsibility for understanding the problems they face: “it is broken”. Ultimately, project scope cannot be managed when there is no meeting of the minds on what are the larger tasks at hand.
  • Snare two: The customer cannot participate in their own treatment. Due to many surreal disconnects too many project resources are spent teaching the customer their own business; too few project objectives are being accomplished.
  • Snare three: The customer provides fake praise and misleading recognition. The project believes it is accomplishing worthy goals and that customer value is being created; it is not.
  • Snare four: The customer manipulates and ties up valuable resources. The more the project starts to unravel the more the Pakled-customer latches on to your team, drawing them deeper into their dysfunction.

At the heart of the “Pakled-Customer Syndrome” are the classic differences in expectations, especially around roles and responsiblities, that lead to conflict. In addition, there are implicit and hidden agendas which must be explicated before meaningful project progress can be made.

The SDL Static Analysis Story

With the two day Microsoft Security Development Conference starting tomorrow in DC, I am curious to hear about one thing: what is the static code analysis story in the Security Development Lifecycle?

Microsoft explains their vision of the Security Development Lifecycle and provides SDL Practice #10: Perform Static Analysis. On that page, under the heading of Tools specific to this practice, CAT.NET is recommended and download links are provided. However, the links are to CAT.NET version 1.0. What happened to CAT.NET 2.0?

On the MSDN blog a post from the SDL folks implies that security-oriented code analysis is going to be part of Visual Studio 11. I believe there is a lot of value in having a separate tool, like FxCop, to perform static code analysis across VS projects and solutions and on 3rd-party assemblies.

I would love to hear more about the tools specific to SDL Practice #10: Perform Static Analysis, and I am hopeful that this will be described in detail in one or more sessions at some future SDC.

The Power of Free

A world-class education continues to become more affordable. The information is disseminating faster and at lower cost. Access to knowledge and new understanding is now mostly limited by your time, attitude and motivation.

MIT OpenCourseWare

MIT OpenCourseWare (MIT OCW) is an initiative of the Massachusetts Institute of Technology (MIT) to put all of the educational materials from its undergraduate- and graduate-level courses online, partly free and openly available to anyone, anywhere.

Source: From Wikipedia, the free encyclopedia (naturally)

This is a great way for people around the world to get a first-class education. Especially in the fields of engineering and science. However, I’m guessing an MIT degree still requires admission, matriculation, tuition, room, board, and other expenses. The learning is mostly free. The biggest investment seems to be your time.
For more information:


The Machine Learning course, broadcast live from Caltech in April-May 2012.

There is an awesome trend happening. One that I believe will benefit all humankind.

How do you apply this to your software development projects?

Free Open Source ASP.NET Applications

The Microsoft ASP.NET site ( offers a lot of free educational and training material.

Look around. There are bunches and bunches of educational material offered free-of-change.

Added 3-May-2012

  • edX is a joint venture involving Harvard and MIT with the goal of improving the quality, effectiveness, and global reach of online university classes.

Added 13-Apr-2012

  • Udacity offers free online university classes for everyone.
  • offer courses from the top universities for free.

Build Numbering and Versioning

Build numbering is a topic filled with “political” and “cultural” significance. I mean that within organizations and among developers, we have heated debates over the numbering of software versions. Is this software 2.3 or 3.0? Or should it be, 2.3.5.rc-1, or 2.3.5.beta?

Phil Haack recently offered some important information on Semantic Versioning (SemVer) specification and NuGet build numbering. Since the SemVer convention is a rational and meaningful way to version public APIs, it’s a good one to follow. Here are Phil’s posts:

The basics of SemVer: the version number has three parts, Major.Minor.Patch, which correspond to:
Major: Backwards incompatible changes
Minor: New features that are backwards compatible
Patch: Backwards compatible bug fixes only.

Everything after these three numbers is for a development organization to use, as it sees fit. Personally, I like ever-increasing, always-unique-for-a-major.minor-version integer numbers. Whether these are build numbers or revision numbers they can be managed by the build script or the continuous integration server.

However, build numbering and versioning has political and cultural significance and implications. Sadly, developers cannot always follow rational and meaningful numbering schemes.


The Marketing Department of a commercial software company often wants to control the first two digits of the build number. They love to promote things like the company’s software is no longer version 2.3; now it’s 3.0! This change in major version generates interest and drives upgrade sales. In some cases, the software is a major new release, with significant new features. In other cases, it is just a marketing gimmick; there are only bug fixes and cosmetic changes in the new version.

Internally, developers hate it when Marketing overstates the major and minor version numbers of software. They feel that a minor release does not warrant an increment of the major version number. They want to follow systems like SemVer.

My opinion: As long as the numbers don’t violate the conventions of SemVer, let the major and minor version numbers belong to Marketing.

Marketing controls the product name. I have seen some crazy product name changes come from Sales and Marketing. As long as it isn’t too absurd, I go along with it. Why shouldn’t that be the same way with the major and minor version numbers? If Marketing wants 2.2 to be followed by 3.0, that’s OK with me. Going from 2.2 to 2.5 could represent a more accurate description of the perceived improvement. Either way, I don’t see it as my call. What I don’t like is jumping from 2.2 to 5.0 or regressing from 2.2 to 1.7, that’s absurd. The major version number should never increment by more than one. The combined major and minor number should always represent a decimal number greater than the prior version. Similarly, going from 2.2 to 2.3 must only introduce backwards compatible new features and backwards compatible bug fixes.

Bottom line, let Marketing own the major and minor version numbers. Insist that they follow the basic rules. Give them the guidance that increasing the major version number means “breaking changes are introduced”, “significant new features are added” or “it’s a total rewrite.” Minor version numbers are incremented when minor enhancements are added and bug fixes are made. Marketing must not break the paradigm. They are adults. If they are using sound judgement, let them own the major and minor numbers.

NuGet and the Nu World Order

In the .NET world, NuGet is very significant. With version 1.6, NuGet follows the SemVer specification. My current thinking on version numbering is that you ought to follow the version numbering that NuGet follows. The NuGet documentation describes the SemVer spec and what NuGet expects of version numbering.

Continuous Integration Server

The CI server is a great way to control and increment the version number.

Cruise Control .NET (CCNet) has the Assembly Version Labeller and TeamCity has the AssemblyInfo Patcher.

Incorporate this version numbering into your build script. Chapter 9 of Pro .NET Best Practices covers this topic. The free code samples are available at the bottom of the Apress page for the book, here.

Here is a good way to version assemblies:

Ben Hall describes how to increment the build numbers with MSBuild and TeamCity:

Wikipedia, as usual, has a comprehensive entry on the topic of software versioning:

Liberate FxCop 10.0

Update 2012-06-04: It still amazes me that not a thing has changed to make it any easier to download FxCopSetup.exe version 10 in the nearly two years since I first read this Channel 9 forum post: As you read the Channel 9 forum entry you can sense the confusion and frustration. However, to this day the Microsoft Download Center still gives you the same old “readme.txt” file instead of the FxCopSetup.exe that you’re looking for.

Below I describe the only Microsoft “official way” (no, you’re not allowed to distribute it yourself) — that I know of — to pull out the FxCopSetup.exe so you can install it on a build server, distribute within your team, or to do some other reasonable thing. It is interesting to note the contrast: the latest StyleCop installer is one mouse click on this CodePlex page:

Update 2012-01-13: Alex Netkachov provides short-n-sweet instructions on how to install FxCop 10.0 on this blog post

Quick, flash mob! Let’s go liberate the FxCop 10.0 setup program from the Microsoft Windows SDK for Windows 7 and .NET Framework 4 version 7.1 setup.

Have you ever tried to download FxCop 10.0 setup program? Here are the steps to follow, but a few things won’t seem right:

1. [Don’t do this step!] Go to Microsoft’s Download Center page for FxCop 10.0 (download page) and perform the download. The file that is downloaded is actually a readme.txt file.

2. The FxCop 10.0 read-me file has two steps of instruction:

FxCop Installation Instructions
1. Download the Microsoft Windows SDK for Windows 7 and .NET Framework 4 version 7.1.
2. Run %ProgramFiles%\Microsoft SDKs\Windows\v7.1\Bin\FXCop\FxCopSetup.exe to install FxCop.

3. On the actual FxCop 10.0 Download Center page, under the Instructions heading, there are slightly more elaborate instructions:

• Download the Microsoft Windows SDK for Windows 7 and .NET Framework 4 Version 7.1 [with a link to the download]
• Using elevated privileges execute FxCopSetup.exe from the %ProgramFiles%\Microsoft SDKs\Windows\v7.1\Bin\FXCop folder


On the FxCop 10.0 Download Center page, under the Brief Description heading, shouldn’t the text simply describe the steps and provide the link to the Microsoft Windows SDK for Windows 7 and .NET Framework 4 version 7.1 download page? That would be more straightforward.

4. Use the Microsoft Windows SDK for Windows 7 and .NET Framework 4 version 7.1 link to jump over to the SDK download page.

5. [Don’t actually download this, either!] The estimated time to download on a T1 is 49 min. The download file is winsdk_web.exe is 498 KB, but under the Instruction heading the explanation is provided: The Windows SDK is available thru a web setup (this page) that enables you to selectively download and install individual SDK components or via an ISO image file so that you can burn your own DVD. Follow the link over to download the ISO image file.

6. Download the ISO image file on the ISO download page. This is a 570 MB download, which is about 49 min on a T1.

7. Unblock the file and use 7-Zip to extract the ISO files.

8. Navigate to the C:\Downloads\Microsoft\SDK\Setup\WinSDKNetFxTools folder.

9. Open the file within the WinSDKNetFxTools folder. Right-click and select Open in new window from the menu.

10. Switch over to the details file view, sort by name descending , and find the file that’s name starts with WinSDK_FxCopSetup.exe … ” plus some gobbledygook (mine was named “WinSDK_FxCopSetup.exe_all_enu_1B2F0812_3E8B_426F_95DE_4655AE4DA6C6”.)

11. Make a sensibly named folder for the FxCop setup file to go into, for example, create a folder called C:\Downloads\Microsoft\FxCop\Setup.

12. Right-click on the “WinSDK_FxCopSetup.exe + gobbledygook” file and select Copy. Copy the “WinSDK_FxCopSetup.exe + gobbledygook” file into C:\Downloads\Microsoft\FxCop\Setup folder.

13. Rename the file to “FxCopSetup.exe”. This is the FxCop setup file.

14. So the CM, Dev and QA teams or anyone on the project that needs FxCop doesn’t have to perform all of these steps copy the 14 MB FxCopSetup.exe file to a network share.

That’s it. Done.

Apparently, a decision was made to keep the FxCop setup off Microsoft’s Download Center. Now the FxCop 10 setup is deeply buried within the Microsoft Windows SDK for Windows 7 and .NET Framework 4 Version 7.1. Since the FxCop setup was easily available as a separate download it doesn’t make sense to bury it now.

Microsoft’s FxCop 10.0 Download Page really should offer a simple and straightforward way to download the FxCopSetup.exe file. This is way too complicated and takes a lot more time than is appropriate to the task.

P.S.: Much thanks to Matthew1471’s ASP BlogX post that supplied the Rosetta stone needed to get this working.

The Virtues of Blogging

I recently attended an INETA Community Leadership Summit meeting where Scott Hanselman made a point of highlighting the relative power and importance of blogging.

The main point he made was that each of us frequently communicates to and within a limited group. Those same email threads or conversations would benefit the Microsoft community, both IT pro and development, more if that same dialog made it into the blog-o-sphere. A blog post is one of the most effective ways any individual software professional can help the community. Especially, if the post provides *constructive* criticism — tact is important — then the post can positively influence change; many people read and take notice of blog postings.

Also, not all communication forms are equal. Many are ephemeral with limited distribution, but a blog is more permanent and far-reaching.

Consider the time it takes to write an email. Let’s say your email raises an issue, points out an inconsistency, explains how to overcome a technical obstacle, or describes an effective way to perform common tasks. Instead of putting that info in an email that reaches dozens of people try writing it up in a blog post; potentially reaching hundreds or thousands of people.

The post may never be read. The blog site may never be visited; however, if your email has a link to your post then the content still reaches the same dozen people with the same number of keystrokes. Nonetheless, it’s not about followers, it’s about adding your voice to the community, without regard to how many people will read it but in a fervent belief that at least one reader, beyond my current circle of influence, will read, understand and appreciate what I have to say. Write it globally; socialize it locally.

Scott delivered a good sermon that I thought I’d share. Let’s see if it has any impact on me. Perchance this is the type of rational argument that motivates me to blog.

I guess you’ll know that I’ve taken the prescription when I create a blog and title my first post: “The Virtues of Blogging”.