Progressive Development : design

Motley says: "Developing international software is really, really hard. We need a brand new version."

James Waletzky — Tue, 16 Sep 2008 18:11:00 GMT

Summary

Motley: Developing international software is really, really hard. We need brand new binaries to ship in other languages.

Maven: Follow these tips when developing for international markets: design for one worldwide binary, ensure the software is globalized, do not build strings at run-time, expand UI labels by 40%, and test with pseudolocalized builds.

______________________________

[Context: Motley is a little shocked that the marketing team has asked the development team to produce a non-English version of the software they just shipped]

Motley: Arrrrrrggggghhhh. I've had it! We spend all this time shipping the first version of our software in English, and now the marketing team wants us to ship a Japanese version to expand our reach. I don't know the first thing about shipping software in languages other than English. It's too hard to do if you don't speak the language. We are going to have to hire a vendor to fully create a new version.

Maven: Calm down, Mot. It's not so bad. If you designed the software correctly from the beginning, shipping in another language really is not that difficult.

Motley: Okay, don't keep me in suspense. How does one "design the software correctly from the beginning?" I have to admit that we were not thinking about shipping an international version, and instead focused on getting the thing done as soon as possible in our default language - English.

Maven: There are various keys to shipping software in multiple languages. The first is to have one worldwide binary.

Motley: How can we ship one binary? If we ship English and Japanese, that will mean two different binaries that we have to build and distribute. Use your head, Mave!

Maven: Actually, no. Ultimately you want one executable for your application that is used regardless of what language is displayed in the UI. The user can potentially set the locale via the Windows control panel to switch languages, which does not change the .EXE that gets launched when the application icon is double-clicked. What does change, however, is what strings are loaded by the executable.

Motley: Ah, of course. That's what I meant. And, hmmmmm…. Fortunately we did use resource files for the UI strings for the most part to make it easier on the user experience people to make sure we developers who don't talk good English get our mistakes fixed.

Maven: Nice play on the grammar, Mot. The other benefit of being able to pass the resource files to user experience people is also being able to pass them to localizers for translation to other languages like Japanese. To do this, however, you need every visible user string in those resource files. Did we do that?

Motley: Well, probably not every string. We'll have to do a scrub of the strings. Shouldn't be a problem though. So that's it?

Maven: Not necessarily. You have to follow a few other rules. Firstly, do not build strings at run-time.

Motley: What exactly does that mean? Let's take a simple example: if I ask the user for their name and I want the software to say "Hello", I have to do something like: "Hello" + name. No real way around that.

Maven: Yes, that type of functionality is often required. However, there are better ways to put strings together. For example, in C# you want to do something like:

string.Format("Hello, {0}", name);

But remember, the string above is actually taken from a resource file. That gives the localizers the opportunity to change the positioning of the token in the string to match the language being translated. Some languages may force different locations of the name in the string. If you build the string in code with the '+' operator, the ordering is compiled in and you have to rebuild (and generate another binary) to change order if another language is "<name>, <hello>" instead of "<hello>, <name>".

Motley: At least the solution is easy. What else do we need to do?

Maven: Another big rule is to expand your UI labels by approximately 30% to 40% in length. In some languages, like German, a typical phrase has many more words/characters than the equivalent English phrase. As a result, just because your UI looks great for English does not mean that text will not be clipped for other languages. Have to be careful there.

Motley: Rules, rules, and more rules. Can't we just abbreviate for the other languages? I am kidding of course.

Maven: Additionally, don't forget that you should not make any assumptions about sort order, date/time formats, currencies, and other international differences. For your software to be truly globalized, it must work with any culture - even when Windows is set to display right-to-left instead of the standard left-to-right.

Motley: One thing at a time. Let's just focus on making v1.1 localizable (translatable to other languages) and globalized (functions correctly in differing cultures). We will likely have to make small modifications to our designs to accommodate this. But here is another question: I don't speak Japanese, so when we have a Japanese version available, how am I supposed to debug it? I want to avoid constantly switching between a Japanese and English build.

Maven: Great question. For initial testing that finds the vast majority of problems, as well as easier debugging, we can create what is called a pseudolocalized build.

Motley: Pseudo-what??

Maven: Pseudolocalized. We take a build that is localizable, and automatically insert some more, well, troublesome characters. We could insert accented 'e' characters to replace the 'e', as well as other characters that are similar to their English counterparts, thus still making phrases readable. In addition, the lengths of the strings are expanded, and each string starts with a delimiter character like '[' and ends with ']'. If you see a string in the UI that does not start and end with those characters, then you have a clipping bug. Pseudo-localized builds really help nail down international problems early in the development cycle.

Here is what a pseudolocalized application could look like:

Motley: Very cool. A lot of it looks like gibberish, but is still English-readable. The UI contains a lot of the characters that can be troublesome given the wrong font choice for the UI. I can definitely see this technique saving lots of bugs prior to check-in, provided the developers can generate a pseudo-localized build on their own.

Maven: Exactly. Since pseudolocalized builds really only require processing of resource files, they are generally easy to generate. The are tools out there that can do it for you, or you can write your own text processor to do simple string expansion and replacement. It's a valuable tool.

Motley: Good tips for a change, Mave. I guess we have some work to do to really make our software internationalized, but I don't feel it will be a lot of work given the choices we have already made. I better get to work!

______________________________

Maven's Pointer: There are lots of other tips to creating good international software, from requirements to development to testing. As a developer, it is little extra work to make your application localizable and globalized. Do this work up front - trust me. I was on a software project that lasted 6 months while we moved strings around. Not exactly fun work. If we had followed the tips above, avoided text in graphics (hard and expensive to translate), and avoided hard-coded user-visible strings in the code, we would have been in great shape to ship in multiple languages. Do it right the first time, and take the very minor hit to the schedule that comes with it.

Maven's Resources:

Developing International Software, 2nd Edition, by Dr. International, Microsoft Press, ISBN: 0735615837, November 2002.
NET Internationalization: The Developer's Guide to Building Global Windows and Web Applications, by Guy Smith-Ferrier, Addison-Wesley Professional, ISBN: 0321341384, August 2006.
Wikipedia entry on Pseudolocalization: http://en.wikipedia.org/wiki/Pseudolocalization

Motley says: "Don't be anal about API design"

James Waletzky — Thu, 12 Jun 2008 08:46:00 GMT

Summary

Motley: Don't be anal about Application Programming Interface (API) design.

Maven: Good APIs are discoverable, consistent, simple, usable, hard to misuse, cohesive, lack side-effects, strongly typed, documented, has tests and samples, extensible when necessary, and are developed with anal minds.

______________________________

[Context: Motley has just been involved a design review for a companion team and has some concerns he is sharing with Maven]

Motley: I am not sure about this. I just attended a design review with Murdoch's team. The issue at hand was a new API they were designing for clients to talk to their logic layer. Their piece is in native code, which I am not that fond of, but design is design no matter what language. This is the fourth API in a row that I have been reviewing that simply extends the IOleCommandTarget interface in COM.

Maven: What's the issue with that API? Forgive me, I do most of my development in managed code.

Motley: Here is the API for IOleCommandTarget::Exec() directly from MSDN:

HRESULT Exec(

const GUID *pguidCmdGroup, // Pointer to command group

DWORD nCmdID, // Identifier of command to execute

DWORD nCmdExecOpt, // Options for executing the command

VARIANTARG *pvaIn, // Pointer to input arguments

VARIANTARG *pvaOut // Pointer to command output

);

You typically use this API to enable some kind of object and the container that it sits in to dispatch commands to each other. It's mostly used with toolbars and menu items.

Maven: Ah, yes, the old "command" API. I worked with a developer in the past who threw one of those into every API set so that he could extend it without publishing a new interface. It became a big grab bag for every little extension and got out of control real fast. At least the Exec() method above is somewhat typed - his command API took in a string that indicated what the method should do. You may as well have that one API as your object model and that's it!

Motley: I don't want to be anal about the design review. This one isn't so bad, but it can be overused, in my opinion. The APIs Murdoch's team are adding to the product are not meant to be used by third parties - they are internal APIs. Why rely on a command-based API set if the APIs are internal?!?

Maven: That's a good question. What was his answer?

Motley: Consistency. They already have a bunch of extensions using Exec() so they are just adding more to be consistent.

Maven: Sounds like some refactoring is in order for the internal APIs. Even for public APIs, unless there is some post-ship customer extensibility, I would not likely follow this model.

Motley: I am having a tough time convincing him that this API approach is suboptimal. I am about to give up. I hate asking this, but any advice? Should I continue to pursue this issue or concede defeat and fight another battle?

Maven: Well, we have talked a lot about design already, and most of those principles hold here. API design, however, is an art that has principles in itself.

Motley: I know of some good examples. There are many examples of good APIs inside the .NET framework. You can get by with just Intellisense for the most part when developing against many of the classes. Well, that is if you forget about ADO.NET for a little bit. I have to relearn the ADO.NET APIs and reread the documentation every time I develop something in that framework, but I digress. And don't get me started on the SharePoint APIs - "site" vs. "web" anyone?

Maven: You are right - .NET holds many good examples. Now based on those examples, what makes the APIs you mention "good"?

Motley: Let's see. Discoverability is high. I can pretty much guess the namespace, object name, and method name much of the time. Microsoft has named the APIs very intuitively so I don't need to rely on documentation other than the Intellisense comments.

Maven: That's a good one! APIs that are easy to find, even without docs, make development a pleasure. What else?

Motley: Along the same lines, APIs should be consistent with the rest of the system. I should just "know" the namespace it's in and the names should make it easy to understand the responsibility of the object or method.

Maven: Good stuff! Keep going.

Motley: Simplicity is also key. I want to avoid jumping through hoops just to use an API. Back to our design principles - coupling can get in the way of simplicity here if I have to create one object before another before I can use the API I really want. I should be able to easily explain what one API does, it should meet the needs of the audience, and there should be few parameters.

Maven: You can tie many of these things up into ensuring APIs have a high degree of usability. Usability does not just apply to user interfaces, but also developer APIs. To complement that, the API should be hard to misuse. Make it difficult for a developer to make a mistake. The IOleCommandTarget interface above is easy to misuse based on the generic in and out pointers. It also contains many parameters, which is contrary to your last statement. Anything else to add to designing great APIs? What else don't you like about IOleCommandTarget?

Motley: It should do one and only one thing (i.e. be cohesive) and have no side-effects. You could argue that the IOleCommandTarget really does only one thing - dispatch commands - but it folds up much functionality within it. I also want my interfaces to be strongly typed so that any mistakes I make are caught at compile-time vs. run-time.

Maven: Wow, Mot, those are some fantastic tips! Any more?

Motley: That about covers it for now. I guess I didn't need your advice after all. BUT, as I have come to know Mr. Always-Has-The-Last-Word Maven, I am willing to bet my paycheck that you have a few more things to add.

Maven: That's a bet I am NOT willing to take! You know me too well, Mot. Here are a few more. Good APIs:

Are documented. In the world of managed code, always supply XML comments with your APIs. As you noted earlier, Visual Studio's Intellisense parses the comments and shows them to developers while they are editing. This is a great help.
Has tests and samples. Why not provide your unit tests with your APIs, at least to internal teams? They provide an indication of how the API is used and what kind of boundary conditions there are. Sample code is also extremely important, both internally and externally. Most developers start with a sample and build from it. As a result, samples need to be of extremely high quality as they form the basis for much (eventual) product code.
Are extensible, but only if you need it. There should be a good reason for extensibility, otherwise you expand your test matrix and open yourself up to all sorts of creative development from the outside world.
Are developed with anal minds. Yes, that sounds a little weird. Yes, you should be anal when you are reviewing Murdoch's APIs. Once an API is published, you must support it for many years to come. Try your best to get it right the first time. Point out every little issue in an API, no matter how small it seems. Aim for perfection. Be anal when asked to create or review an API!

Motley: This was actually a good discussion. I didn't really consciously realize there was that much to creating a solid API.

Maven: The job of a software engineer is forever complicated.

______________________________

Maven's Pointer: Usability testing applies just as well to APIs as it does to user interfaces. Why not ask for developer volunteers, give them coding scenarios, and ask them to program a small solution to a problem using your new API set? Ask them to think out loud, and ensure you document their every move. It may provide some valuable information on whether your APIs are usable.

Maven's Resources:

http://neuroning.com/articles/2006/11/19/on-api-design-guidelines
The Most Important Design Guideline?, by Scott Meyers, IEEE software, July/August 2004, http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004.pdf

"...interfaces should be easy to use correctly and hard to use incorrectly leads to systems that are both more usable and more likely to be used correctly."

Motley says: "I fear public speaking more than I fear dying!"

James Waletzky — Tue, 11 Dec 2007 17:40:00 GMT

Summary

Motley: Speak at a conference?!? Are you insane?!? No public speaking for me!

Maven: Speaking at a conference is a great way to build confidence and influence not just your company, but the industry.

______________________________

[Context: We'll continue with HPT Part 3 next time. For now, Motley and Maven's buddy James just returned from speaking at a conference]

Maven: Hey - did you hear James just returned from a conference? He actually did a speaking gig at the Agile Development Practices 2007 conference in Orlando from Dec 3-6. He said it went quite well.

Motley: Crazy nut job. Don't you know that the average person fears public speaking MORE than dying? First time I heard that statistic I was quite shocked, yet not surprised all at the same time. There's no way you'd catch me doing that.

Maven: Ah, but it's great experience! What better way to practice your communication skills, meet influential people in the industry, make new contacts, help others, and have a great time while you are doing it! Plus, when you speak at a conference they usually compensate you a little, reimburse some of your fees, and give you free conference registration. Lots of fabulous benefits.

Motley: if you say so. Not sure I could get up in front of 100 people or more and do it. I think I'll expand my scope of influence and work on my communication skills in some other way. What did he speak about anyway?

Maven: A great topic: "Balancing Emergent Design with Big Design Up Front (BDUF)". Here is the abstract:

"Big Design Up Front (BDUF) is a design technique that has been part of the development cycle for decades. Unfortunately, fully specifying a software design in the presence of change without a crystal ball is rarely effective. Agile principles and practices leverage feedback-oriented techniques such as emergent design to embrace change and design “just-in-time.” By balancing BDUF and agile emergent design practices such as test-driven development to avoid “cowboy coding,” we can develop just enough design documentation to guide our development toward the project’s big-picture goals. This balanced approach has been employed successfully at Microsoft to develop large software systems. James Waletzky discusses the pitfalls of BDUF and how agile methods help you reduce design risk. Learn what emergent design is and is not, how refactoring keeps designs clean, and ways to document your design with “just enough” detail. James introduces tools to help your design efforts, including XML comments, Sandcastle, and a C# Design By Contract language extension called Spec#. Take away practical design techniques that will improve your software designs in a world where predicting the future is impossible."

Pasted from <http://www.sqe.com/agiledevpractices/Concurrent/Default.aspx?Day=Wednesday>

Motley: Well, that does sound like a cool topic given other conversations we've had. Can I see the slides?

Maven: Sure. Here they are:

http://waletzky.no-ip.com/download/BalancingEmergentDesignAndBDUF.pdf

NOTE: This is a low-bandwidth connection. Let me know if you want me to e-mail the slides to you in PPTX format.

Motley: There's some good stuff in there. I like the little script. Think it's based on us?

Maven: I wouldn't doubt it. James seems to listen in quite a bit. He was wondering if any of our eavesdroppers have any comments or questions about the topic. Should we pass the word that he would like to hear from them.

Motley: I think you just did. Pay attention, Mave!

______________________________

Maven's Pointer: At Microsoft, to get to the more senior ranks of software development, you have to do a few things well. One is to be technically very good at what you do. Two, you have to expand your scope of influence. This may require some explanation: instead of concentrating on just feature development at small granularity, you have to influence multiple features, a product, a product line or the industry. Three, you need to have good communication skills. Speaking at an industry conference with reputable speakers is a great way to get that experience. I strongly recommend it. Once you get over your initial fear of public speaking (ugh), it's actually quite fun!

James' Pointer: I really enjoyed the Agile Development Practices 2007 conference. If you ever get a chance to go to an agile conference, go. You'll meet lots of great people and you will learn a lot about software development. The Agile Development Practices conference is is happening again in November 2008 in Orlando, and another big one entitled Agile 2008 is from August 4-8, 2008 in Toronto.

Maven's Resources:

Agile Development Practices 2007 Conference Web Site: http://www.sqe.com/agiledevpractices
Agile 2008: http://www.agile2008.org

Motley says: "Performance stinks, but I'll deal with it later"

James Waletzky — Tue, 20 Nov 2007 17:46:00 GMT

Summary

Motley: I'll deal with performance issues when I have something to test. Then I'll run the profiler and just optimize the slow methods.

Maven: Think about performance early in the development cycle. Set goals. Design for performance. Measure, measure, measure. Optimize the scenarios that matter.

______________________________

[Context: Motley is doing some performance testing and optimization on the feature he is building]

Motley: Hey, Mave. Check this out. I've been doing a bunch of performance tuning on this component. I've made these three methods twice as fast as they were before!

Maven: Cool! What tool are you using to measure how fast they are?

Motley: The built-in profiler in Visual Studio rocks. You can run a set of unit tests against your production code and VS will tell you what methods are your bottleneck. Based on that I go in and fix them. For ultimate flexibility, you can choose to either instrument your build with profiling prolog and epilog code in each method, or you can have the VS profiler take frequent samples to see how your application is behaving. I prefer instrumentation - it changes the binary but you get more accurate results.

Maven: Sweet. Why did you just jump to the methods that VS tells you were the slowest?

Motley: Because they're slowest! Duh. I'm not going to go spend valuable time optimizing the fast methods! Have you had your morning coffee today Mave?

Maven: The key is that just because a particular method is slower on a relative basis than other methods for a particular test scenario doesn't mean it's worthy of spending time optimizing. What if the scenario you are optimizing for is rarely used? Is it worth making the 5% of the code that is rarely executed twice as fast? What if the user already perceives that feature to be fast enough given today's hardware?

Motley: Reasonable questions, I guess. But faster is faster. It's never a waste of time to optimize a component.

Maven: With all due respect, Mot, I beg to differ. The time you spend optimizing some component that doesn't really need it from the user perspective is time you could have spent improving code quality, optimizing something that needed it, or building a new piece of functionality to delight the user.

Motley: Grrrr… you mean I am "generating waste", if we talk about being agile. I hate it when you're right.

Maven: Generating waste? Yeah, I didn't think of it that way, but exactly! Nice observation Mot!

Motley: Okay, I'll find out which components need optimizing first and then work on those.

Maven: Great. How are you going to determine which ones need optimization?

Motley: I'll… Hmmm… your telling me I can't just look at absolute numbers. Well… enlighten me Einstein. How am I going to know what to optimize???

Maven: There's nothing wrong with using the profiler for some scenarios as you mentioned previously. Profiling works well when you are executing end-to-end scenario tests that exhibit real-world behavior of the software. For example, use the software in a scenario the way the user would. The bottlenecks that appear in a real-world use case are usually worth fixing. However, if the user already thinks that the software performs well enough for their needs - on standard hardware of course - then focus your efforts elsewhere. You need the voice of the customer (e.g. a user experience person or program manager) to give you that information, however.

There are other types of performance testing you want to do as well that are above the method level. For example, if you are building a web application, you may need to test throughput, response time, and latency. These factors may have more to do with the way you use bandwidth and how machines are configured vs. how individual methods perform.

Motley: I'll have to agree with you there, as scary as that sounds. You have to admit that I was doing the right thing by measuring, however.

Maven: Absolutely! The golden rule of performance tuning is Measure! Measure! Measure! We usually say it three times to ensure the emphasis is made. Don't try to guess at what to optimize as much of the time you'll guess wrong. Leverage a profiler and other testing tools to provide some solid data. Another question: have you been thinking about performance all along?

Motley: What do you mean? I can't fix any performance problems until I know they exist! I deal with performance stuff late in the cycle like any other developer.

Maven: What if you make a bad design decision? I know one team that was trying to determine whether they should redesign their remoting infrastructure from using DCOM to Web Services. Early on they decided to take the plunge and made a heavy investment in web services. Know what happened? Although web services brought benefits in terms of standardization and security, the performance hit they took was huge. Web services infrastructure was tied to the entire application and they couldn't go back.

Motley: Sucks to be them! They should have prototyped or developed using an agile model in small pieces with performance testing throughout.

Maven: Exactly! So why not heed your own advice?

Motley: <silence>

Maven: You need to consider performance from day 1 of your development. Set performance goals to hit. The previous version, if it exists, can be your baseline for performance numbers. Aim to be within at least 10% of those numbers. Think about the scenarios where performance is critical. Plan and budget the resources such as memory and CPU you use accordingly. Prototype new technologies before making a heavy investment in them. If you discover a design flaw related to performance too late, you may not be able to fix it.

Motley: So your best practices for developers when it comes to performance are to:

Measure, measure, measure - don’t guess at bottlenecks
Don't leave performance work to too late in the cycle
Think about performance goals early on, and consider performance when doing design
Test and tune real customer scenarios
Prototype technology decisions that may impact performance

What about Test-Driven Development, though? Where does performance work fit in with that methodology?

Maven: The story doesn't change a whole lot. You still think about performance goals and design impacts. As my buddy Matt says, make sure you don't do TDD with the blinders on as a change in one unit or component can have a significant impact on performance in a seemingly unrelated feature of the product. With TDD you are testing units in isolation, and mock objects help with that. You should think about developing performant code according to the contract in your unit. However, you may not be able to predict the impact on your dependencies. The advice there is to integrate early and often, and start performance testing early and often. Don't leave it until the end.

______________________________

Maven's Pointer: At Microsoft, software performance is treated very seriously, and is basically a feature in a project from day 1. You need to make some intelligent design decisions around performance early in a development cycle, but you want to avoid painting yourself into a corner if you make the wrong decision. That's why designing to interfaces is such an important design concept. You want your design to accommodate change if you make the wrong decision or you need to plug in a different algorithm depending on some heuristic. Your sorting algorithm may work fine on small datasets, but what if in the field you run across a huge dataset for which there is a better algorithm?

Maven's Resources:

No specific resource around designing for performance and tuning performance due to the tight tie to technology. It is recommended that you search your favorite bookstore for books on performance specific to your technology (e.g. SQL, ASP.NET, C#, etc.) or activity (development, testing).

Motley says: "It's tough to make decisions involving multiple dimensions"

James Waletzky — Tue, 04 Sep 2007 18:40:00 GMT

Summary

Motley: It's tough to make decisions in multiple dimensions, so just pick the most important one. Make the decision and move forward. No need to document the alternatives.

Maven: Pugh Concept Selection (PCS) facilitates decision making where there are multiple alternatives and multiple weighted criteria. A PCS decision matrix provides a nice way to document your thinking.

______________________________

[Context: Maven and Motley are having a brainstorming session about how to design a particular component]

Motley: So far, this has been a fairly productive brainstorming meeting. We have quite a few alternatives to choose from. Let's just go with the first solution - it will perform best.

Maven: But what about the other criteria in choosing a design? What about space considerations? Ease of implementation? Minimizing the number of dependencies? Resource usage?

Motley: All good considerations, but performance is what matters most here.

Maven: You may be right, but if two solutions are both predicted to perform equivalently but one is much harder to implement, wouldn't we want to go with the simpler solution? Remember our design principles we talked about before.

Motley: Yeah, I guess. But the more variables we add here the more difficult it is to see the right solution. I'm pretty sure solution #1 is best.

Maven: Well let's find out. Ever heard of Pugh Concept Selection, or PCS?

Motley: Sounds like some disease with really nasty side-effects.

Maven: Always the wise guy. PCS is a decision making technique invented by Stuart Pugh in 1990 to evaluate how multiple product concepts met key customer needs. It provides a very straight-forward way of evaluating ideas against one another based on some set of criteria.

Motley: Sounds interesting. I like the "straight-forward" part. How do you do it?

Maven: It's actually very easy. You have a decision matrix that identifies:

The various solutions you are considering
The criteria that go into evaluating the solutions
The weighting of each criteria

If we number the solutions from our brainstorming session as 1, 2, 3, and 4 and use criteria to evaluate them such as performance, memory consumption, ease of implementation, impact on setup, and dependency requirements, we get a table like the following:

Criteria	Weight	Solution #1	Solution #2	Solution #3	Solution #4
Performance	5	0	-1	0	-1
Memory	3	0	0	0	-1
Simplicity	5	0	1	1	0
Impact on Setup	1	0	-1	0	1
Dependency requirements	3	0	-1	1	-1
TOTAL	-	0	-4	+8	-10

Motley: Ok, I see what's going on here. We put down all the criteria in rows and all solutions in columns. Each criteria gets a weight assigned relative to its importance. We use one solution as a baseline and compare the others to it. If a solution is better on a particular axis, it gets a +1, if it is about the same as the baseline, it gets a 0, and if it is worse than the baseline, it gets a -1. Multiply each of the +1, 0, and -1 values by the weights, add them up for a particular column, and you get a nice summarized number. The highest number is the best solution.

Maven: Excellent analysis dude! So what does this tell you?

Motley: Well, if our weights and criteria are reasonable, it's actually solution #3 that we should go with and not solution #1. Very useful exercise, I must admit. Sometimes you add some value to the team, Mave.

Maven: And a very simple technique too. Note, however, that it is also easy to misuse. If the weights and criteria are not reasonable, then garbage in, garbage out. The results will not be very meaningful.

Motley: Same is true with lots of things - you put crap in, you get crap out. It takes a really special technique to make diamonds out of coal.

Maven: Nice analogy.

Motley: Great! So let's go with solution #3 and dump this matrix until the next time we need the technique.

Maven: Hold on! Not so fast. There is value in keeping this matrix around, particularly as the appendix to a design document. It summarizes the alternatives that you thought about and why you chose a particular one, and the summary fits nicely on less than a page. You never know when someone will want to validate or learn about your reasoning. Plus, if your memory is anything like mine, you might forget down the road why you chose a particular alternative.

Motley: Fine, if it gets you off my back, I'll put it in the design doc. Hmmmm… maybe I'll use it at home to figure out my next big purchase at bonus time.

Maven: Pugh Concept Selection is definitely a useful technique both in and outside the office to put a frame around your thinking. And with your bonus money, I recommend some charm school lessons.

Motley: Ouch! A dig from Maven! You know you have just escalated the battle, right?

______________________________

Maven's Pointer: Sometimes comparing all solutions to an arbitrary baseline does not yield a stand-out winner. Often this happens because the assignment system of +1, 0, and -1 does not provide enough variance between alternatives. Stretching the assignment system to +2, +1, 0, -1, and -2 can help when one solution is clearly superior or inferior to another.

Maven's Resources:

Design for Six Sigma, by Greg Brue, McGraw-Hill, ISBN: 0071413766, May 2003.

Motley says: "My design is done when the schedule says it's done"

James Waletzky — Tue, 31 Jul 2007 18:18:00 GMT

Summary

Motley: Design is done when that 3 day period I have to do design has expired.

Maven: Design is done when your stakeholders are satisfied. Stakeholders include you, your peers, the test team, architect, future maintainers, your manager, and customer support.

______________________________

[Context: In a continuing conversation about design, Maven asks Motley an important question]

Maven: Mot, so based on all this stuff about design principles and how to judge whether a design is good, how do you know when you are "done" with design?

Motley: Here's the way it works - we create a schedule for development, and I typically have a few days for the design phase. When I use up that time, my design is done. If it happens to be three days, then at the end of that three days, I'm finished - on to coding.

Maven: What if you still have unexplored areas?

Motley: I'll figure it out during coding. We did talk about emergent design, right?

Maven: You're right - some details will emerge as you are coding, but there are some big picture things you need to nail down during your so-called design phase.

Motley: Yeah, and we get three days for that. Are you hearing okay today?

Maven: We need to be more scientific than that. Some tasks should be time-boxed, but design really isn't one of them. Let me start with this question - who are you doing design for?

Motley: Me! I want to think about the problem up front such that I have confidence to get the code written with minimal mistakes.

Maven: Great start! Who else is design for?

Motley: Ummm, myself and I? What are you talking about?!?! I do design for me - no one else.

Maven: Here's where the confusion lies. Your design is not just for you, but other stakeholders in the project. Here are a few:

Yourself: You mentioned this already - you want to have confidence that you have thought through the high-level details enough to proceed.
Your peers: How can someone review your ideas if they don't have anything to review? Creating at least a minimal design document (could be photos of a whiteboard) is necessary to help others validate your thinking.
Test Team: In order for the test team to do their jobs and create automation test suites, they need to know what developers have in mind for the design. Testers want to know how testability hooks will be placed in the design, and, for example, how they will go about performance testing. They have several needs of the design.
Architects: If your team has an architect, that person will want to validate that your feature fits in with the overall technical vision of the product. An architect will probably want to see a layer diagram, integration details, how errors are handled, and other information.
Future maintainers: The next person to maintain your code will be much better off with an up-to-date design document to get them started. The high level details that a design provides is a great lead-in to the code.
Your manager: A technical manager will want to know what you have planned.
Customer Support Services: CSS will want to know what supportability hooks you are planning so that they can plan their support mechanisms for the product. Some CSS teams will not even accept your product for support without a design document, particularly if they do front-line on-site support.

Motley: I think you've been sniffing glue again. If I do design to satisfy all those stakeholders, my document will end up being 150 pages long and I'll need much more than three days to do design!

Maven: Don't get carried away, my friend. Agile and lean say to do "just enough" and cut down on wasted effort. You want to talk to each of these (groups of) people beforehand to find out exactly what they need from the design. If the answer comes back as "nothing", then don't bother with that piece of the design. Get expectations up front and do your best to satisfy them. Once you have expectations set, you'll know exactly how much to do and nothing more. Plus, you can make a much more reasonable estimate on how long design will take instead of just time-boxing the time.

Motley: So if my peers, for example, just need a class diagram with a bit of explanation of what I am doing, that's all I should do?

Maven: You bet. Do just enough to satisfy everyone's needs.

Motley: I bet I could come up with a nice minimal doc template that guides the developers on the team when doing design. I just need to interview the various groups to find out what they need. I like this lazy approach - do the least amount needed.

Maven: You have some great ideas, Mot. I'd love to see the template when you're done!

______________________________

Maven's Pointer: Combine a nice minimal design doc template with a good checklist that acts as a reminder to check, for example, design principles. And also note that a "doc template" does not necessary imply a MS Word document template. You could just as easily store your design documentation in a more collaborative space like a wiki.

Maven's Resources: None this time

Motley says: "A good design is all in the eye of the beholder" (Part 2)

James Waletzky — Tue, 24 Jul 2007 22:51:00 GMT

Summary

Motley: Judging a design to be "good" is very subjective.

Maven: "Good" designs satisfy fundamental design principles, like separating creation from usage, encapsulating variability, preferring containment to inheritance, and designing to interfaces.

______________________________

[Context: Maven and Motley are at lunch, picking up where they left off with their discussion on design principles]

Maven: So, um, where, um, were we?

Motley: Stop talking with your mouth full, man! You know how annoying that is?

Maven: <Gulp>. Sorry about that. You know how I like to talk! Anyway, I think we left off with the DRY principle, for "Don't Repeat Yourself". Another good principle to abide by is to separate creation from use.

Motley: You mean like giving up your baby for adoption?

Maven: Oh, that was just a really bad joke - I'll pretend it never existed. Have you ever heard of the abstract factory pattern? That pattern exists to satisfy this principle. The idea is that you really don't want to have "new" littering your code base, particularly for objects that are created based on some dynamic logic or have some complicated initialization. By decoupling object instantiation from the actual usage of the object, the client can remain in the dark as to what kind of object it is actually using, helping us to adhere to our earlier principle of loose coupling.

Motley: Although, I guess if I only use an object one time and it is simple, there is no harm in creating it directly and not using a factory.

Maven: You bet. This is almost a guideline instead of a principle, but just use it intelligently and remember there are always exceptions. Another principle we should talk about is encapsulating variability. You want to examine your domain and when creating your design find what is common and what varies. Do something called "Commonality-Variability Analysis". You create abstractions from what is common and derive the variabilities from these common abstractions.

Motley: So with our development team, the commonalities between us would be that we're all Developer abstract base classes with a Code() method, and the variabilities would be that most of us are GreatDeveloper subclasses and that you are an AnnoyingDeveloper subclass.

Maven: I am sensing a high level of respect here. Yes, you are basically correct in the semantics of your example. The next principle is prefer containment over inheritance. With deep inheritance hierarchies you are tightly coupled to base implementations at run-time, creating a kind of "white box" reuse. It is hard to change behavior without recompiling. Alternatively, with containment, you can replace object instances at run-time to change behavior, reuse is more "black box" (i.e. you only need to know about the interface), and you are only coupled to an interface - that's it.

Motley: In my previous example, I'll hold a pointer to a Developer class, which is just an interface, and as a client I'll never really know whether I'm referring to an AnnoyingDeveloper like you or a GreatDeveloper like me. This is particularly true if I create it through a Factory or something that creates me the right one via a configuration file or some other dynamic mechanism.

Maven: You are a quick study, as I keep saying! The last principle I want to talk about is design to interfaces. You can probably guess from the other principles that this one was coming, but it's worthy of pointing out since it is so important. Having components in your design communicate through well-defined interfaces has many advantages, including being able to replace implementations as needed and decoupling as much as possible, both at build-time and run-time. This technique also has fantastic testability advantages - I can replace any implementation with a mock object that helps me write lightning quick tests which, as we discussed, is a key property of unit tests.

Motley: Well-defined interfaces, kind of like the way my fist fits squarely in your gut <pow!>. I am not quite sure what a "mock object" is, but I am guessing your standard response applies "we'll talk about that later."

Maven: Ugh. Thanks for the shot to the stomach - much appreciated <sigh>. And yeah, we'll talk about mocks later. <Cough> I think you knocked the wind out of me! Anyway, if you can put all those principles together, you are well on your way to a "good" design. It doesn't guarantee it, but you'll have much higher odds.

Motley: So to summarize, here is what you are saying are the design principles that go into making a design "good":

Loose coupling
High cohesion
Simplicity
No undesirable redundancy
Separate creation from use
Encapsulating variability
Prefer containment to inheritance
Design to interfaces

______________________________

Maven's Pointer: If you just think about making your designs testable, you'll find that you will automatically satisfy many of these principles. A testable design needs to be interface-oriented (for mocks), allow creation of object instances for testing, loosely coupled (or tests become difficult to write), and take advantage of containment (to replace instances).

Maven's Resources:

Commonality-Variability Analysis, from the NetObjectives July 2004 Ezine
Design Patterns: Elements of Reusable Object-Oriented Software, by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides, Addison-Wesley, ISBN: 0201633612, 1995.

Motley says: "A good design is all in the eye of the beholder" (Part 1)

James Waletzky — Tue, 17 Jul 2007 19:49:00 GMT

Summary

Motley: Judging a design to be "good" is very subjective.

Maven: "Good" designs satisfy fundamental design principles, like loose coupling, high cohesion, simplicity, and no undesirable redundancy.

______________________________

[Context: Motley is wondering how to really judge a design is "good". This conversation picks up immediately from the last one]

Motley: … Like I said, a good design is all in the eye of the beholder. One developer may judge a design as good, and another may not. Probably depends on what they had for breakfast.

Maven: While there is some truth to that statement - good design is subjective - generally a good design is one that meets a few key characteristics:

The design satisfies certain fundamental design principles
The design is "done" (let's talk about what that means next time)

Motley: And what principles would those be? You mean common computer science ideas like coupling and cohesion?

Maven: You bet! Those would be two good design principles. Let's start with those. Coupling is the degree to which software components depend on other software components. You want components to be loosely coupled to make components easier to test, shorten the build process, foster reuse, and ease deployment among other things. Avoiding cycles is also super important.

Motley: Of course, you also want the relationship with your significant other to be tightly coupled.

Maven: Nice pun hotshot. Cohesion often goes with coupling - it measures the functional relatedness of a component or within a component. Highly cohesive components decrease the risk of change (components have one responsibility), eases testing, and promotes reuse.

Motley: Alternatively, a component should have only one reason to change. What else?

Maven: Keep it smart and simple. As we discussed with agile practices, keeping things simple is important. Simplicity helps keep quality up, eases maintenance, and leads to better reliability. This is arguably the most important principle in a good design.

Motley: Of course, it can be hard to judge simplicity.

Maven: Yes, but for example, highly parameterized over-engineered software is harder to understand than more static software. That's one gauge. You can also go back to basics and judge simplicity with simple rules like 7 +/- 2. If an interface contains more than 7 methods (approximately), it is going to be difficult for someone to keep them all straight. There is a reason why phone numbers (ignore the area code) are seven digits - that's about all the concepts we can keep straight in our short term memories at one time.

Motley: Although when I meet a girl, I write it down regardless because I don't want to forget it!

Maven: Yeah, I guess that is safe. Another principle we should talk about is the DRY principle.

Motley: "Disregard Recommendations from You?"

Maven: Ha, ha, Mr. Smartypants. It stands for "Don't Repeat Yourself." Avoid duplication by abstracting out things that are common and placing those things in a single location. Undesirable redundancy can be really evil - it makes change more difficult, there is duplicated effort, it leads to contradictions, and leads to increased complexity, which violates the simplicity principle.

Motley: I agree. I can't tell you how many times I've missed fixing a bug somewhere else in the code because it was copy/pasted from somewhere else. Ugh. We call that "clipboard inheritance" and I really, really dislike it.

Maven: Say, why don't we grab lunch and continue this conversation?

Motley: Sure. You buy.

______________________________

Maven's Pointer: Coupling is the design principle that is frequently violated and leads to the most trouble. Tightly coupled systems are extremely difficult to maintain. There are a lack of "seams" between components that allow you to plug and play different implementations and isolate components from change. Tight coupling creates difficulties in testing and change in dependencies have effects on more components than they should.

Maven's Resources:

http://www.ootips.org,
Agile Principles, Patterns, and Practices in C#, by Robert and Micah Martin, Prentice Hall PTR, ISBN: 0131857258, July 2006.

Motley says: "Refactoring means no more up-front design"

James Waletzky — Tue, 10 Jul 2007 18:08:00 GMT

Summary

Motley: Refactoring keeps my design clean from the start, so no more up-front design!

Maven: Up-front design is still necessary to achieve clarity on the overall approach (preventing rework later) and needs to be documented to allow others to review your thinking.

______________________________

[Context: Motley is trying to educating himself on agile development and is reflecting on some reading with Maven]

Motley: This is really cool - I've been doing some reading on agile development and because I am doing refactoring continuously, that means I can do away with all that up-front design stuff we used to do.

Maven: Do away with it? Hardly! Maybe for a small couple-hundred line program, but any bigger than that, there is still value in thinking through the problem before you code anything - at least, if you want to prevent major rework later in the cycle when mistakes are more costly to fix.

Motley: But refactoring is going to keep my design clean. What's the point of all the up-front thinking?

Maven: That's true - refactoring helps you continuously keep quality high. However, if you make an investment in a bad high-level design and architecture, it becomes extremely hard to refactor yourself out of it. Then you are talking about reengineering, which can be a huge task. Refactoring is for small design changes without changing external functionality. Large changes are not as well suited to refactoring as it may lead to drastically changing the way requirements are implemented.

Motley: But I want my design to emerge based on the learning I get while coding!

Maven: You want the details to emerge, but you need clarity on the overall approach before you flesh out the detail. A design phase is needed to understand the problem, investigate various high-level solutions and their trade-offs, and document your overall approach.

Motley: I'm not sure I buy that - the agile manifesto states that we should favor "working software over comprehensive documentation." No design document needed!

Maven: Not exactly. You stated the keyword: favor. It does not say there is no need for documentation whatsoever. We need that documentation to keep the stakeholders in our design happy and to provide something concrete for people to review.

Motley: And I thought I was done with 100 page design documents…

Maven: You are! You want to document "just enough" in your design. Documents of 100 pages in length are generally overkill and violate the lean principles we talked about previously.

Motley: But how do I know what is "just enough"? If I have 3 days on my schedule for design, "just enough" usually just means I hit the end of day 3.

Maven: Let's save that for another conversation. I have a great way to measure "just enough", but I am going to leave you in suspense.

Motley: Fine. I don't want to be here all day anyway.

Maven: Of course, the other topic of interest is once you have "just enough", you want your design to be "good".

Motley: Great. I want "just enough" - I have no idea what that really means - and I want it to be "good" - I have no idea what that really means either. Judging "good" on a design is all in the eye of the beholder.

Maven: You're comparing judging a design for "goodness" to judging looks?? Hah. Fortunately, we can get a little more scientific than that and focus on the principles that generally make one design better than another. Let's do that...

______________________________

Maven's Pointer: Be careful with the term "emergent design". Many developers equate the phrase "emergent" design with jumping into Visual Studio and coding. What "emerges" at the end is some kind of design (usually junk). Truly "emergent design" uses a feedback technique to provide you continuous confirmation that you have a clean and working design. An example of an emergent design technique is test-driven development (TDD). Tests drive your design, refactoring keeps it clean, and test automation validates it all works.

Maven's Resources: Agile Development Manifesto, Wikipedia entry on Continuous Design