Inconvenient Accessibility Makes Self-Documenting Code

Intentional use of access modifiers (public, private, etc.) is like a clear memo to your team. This came up during Steve Bohlen's Virtual Alt.Net talk on domain-driven design.

Steve explained the distinction between Entity objects, which have a unique identity independent of their properties (Even when I change my name, I'm still me.), and Value objects, which are defined by their properties (If you change the house number in an address, you have a new address.). When dealing with Entities, code should not be able to change the unique id—that would be like someone claiming your social security number and thereby becoming you. Therefore, Entity classes should have private setters for their unique identifiers.

A meeting attendee asked why, since this gets inconvenient when you're creating an object based on a record fetched from the persistence repository. It's a big pain; why bother? The analogy I would offer is this. When you're defining a class to represent an Entity in your business domain, you know it's an Entity. You intend for it to behave and be treated like an Entity. You don't want any of your teammates setting its unique id in their code. So you send them an email: "Don't set Person.UniqueId, okay?" Uh hunh. How well is that going to work over time?

Instead, if you simply don't provide a public accessor to the UniqueId property, your teammates will get the message loud and clear. Granted, someone could edit the code and change the accessibility, but the fact that he or she needs to is a flashing neon sign saying "Stop. Think. Are you barking up the wrong tree?" You've made your code communicative. Its structure conveys your intent. No need for comments; this is an example of self-documenting code.

Giving Mono to my Husband

Holy crossed-platforms, Batman! How did I not know about Mono, the free, open-source framework that will run .NET applications on Linux and Mac OS X?

Not to get too personal, but I'm part of a mixed marriage: I run Windows and develop primarily in C#; my husband runs OS X and is not (actively) a programmer. Through love and mutual respect, we make it work. But what we have so far not been able to make work is my writing handy utilities and toys that he can use on his laptop.

I learned about Mono in Rod Paddock's intro to the May/June issue of CoDe Magazine. Then I came home, had Jon install Mono on his Mac, and gave him a quick little console app I'd written in C#. It ran like a charm. A WinForms app with one button and a popup message also ran, looking distinctly X11-y.

This is super exciting for us. We've been talking about a card-game playtest simulator, to help with his creation of card games. (Jon posts one free board game a month and has a few upcoming commercial releases.) That process usually involves a significant investment in card stock and time with the paper cutter, just to see how hands of cards come together and move through the game. A simulator would help him to vet the first and maybe second drafts of the cards without printing them out. Now that I know I can build something he'll be easily able to run, it's time to start designing!

Got the 0000FFs

Given up on attaching meaning to those three- or six-character codes that define colors in HTML and CSS? Sure, you can use an online color picker, but let me give you a nuts-and-bolts explanation of what they mean. This info is worth having because:

1. It's a time-saver. If you want to make a color a little more blue, or a little less saturated, you can do the math in your head and take care of it right there in your editor.
2. It gives you more options. If you find a cracking color combo in the Color Index, but it's given only in RGB values, you can convert it to HTML-ready values using just math.
3. It's satisfying. Don't you prefer knowing how something works, instead of just how to work with it?
4. It will be diverting. There will be stories, you know me.

Two experiences in my childhood laid the foundation for my understanding of hex color codes, so I will share them with you. (See? Stories.)

When I was very young, I learned that the three primary colors are red, yellow, and blue, and when you mixed them together you got, well, mud, but theoretically black. That's true for pigments (paint and ink; think magazines and newspapers), and if you're going to be pedantic, those pigment primary colors are properly called magenta, yellow, and cyan. (Add blacK and you have CMYK, the other color scheme you'll see mentioned in design books.) But it's a whole 'nother ball game when you are mixing light instead of pigment, and computer monitors are big light bulbs.

My seventh-grade science teacher, Mr. Saeger, created an excellent demonstration that I still think of when I'm mixing up hex color codes. He set up the overhead projector. He placed a square of red cellophane on the projector, and it threw a red square of color up on the wall. Sure. Then he added a piece of green cellophane, and the area where they overlapped was... yellow? That's curious. Last he added a piece of blue, and the intersection of all three was white. It blew my mind.

If you can replicate this effect (shine a light through overlapping colored plastics), it's a great science experiment to share with your kids. It will help you remember the mixing of light colors with the same intuition you have for mixing pigments. And it's cool.

The second formative experience from my youth was working the stage lights in my high school theater. Hanging above the stage were three rows of lights; the lights alternated amongst white, yellow, red, and blue, and were controlled by a huge wall of levers backstage. Big, creaky, ancient things, that really let you know you were working the lights. I had to crouch and get my shoulder under them to move the big ones.

Picture them: Four rows of colored levers, corresponding to each color of light out over the stage. Each lever controlled a light. Down was off, and as you pushed the lever up, the light would gradually brighten. A big handle at the end of a row would move all the levers of that color, so you could, for example, bring up all the whites in unison. You could slowly turn down the yellows over the course of a scene while a teammate pushed up the reds, and make a sunset. You could push all the colors up to make the light full and cheery (and make the stage hotter than a tanning booth), or pull them all down to plunge the stage into darkness at the dramatic conclusion of Act I.

Levers... lights... hex codes, here we go.

Light is mixed from red, green, and blue. (Remember the order: RGB, RGB, RGB.) Computers like to count not from 1 to 100, but from 0 to 255. Think of 0 as off, with the lever all the way down, and 255 as on, with the lever all the way up. To make yellow, you need a lot of red and a lot of green, and no blue, so R = 255, G = 255, and B = 0. To make a paler yellow, you want to bring it closer to white. White is all three on at maximum; therefore you need to turn up the blue. Maybe R = 255, G = 255, and B = 153. To make it more orangey, you'd back off the green. And so forth.

So we have three levers. A hex color code has three pairs of characters. That yellow would be #FFFF00. Put another way: FF, FF, 00. It's the same three RGB values, but in base 16 instead of base 10. 255 in base 10 becomes FF in base 16. Counting in base 16 is like counting in base 10, if you had 6 extra fingers. 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, 10.

The Math Bits site gives a visual explanation of how to convert from base 10 to other bases. Also, you can use the calculator on your computer. In Windows, set the calculator to Scientific mode in the View menu, make sure the "Dec" radio button is marked, type in your base-10 number, then switch to the "Hex" radio button and read the converted value. But usually when I'm writing HTML, I just need to nudge a color a little, not do a whole decimal-to-hexadecimal conversion. So it is sufficient to know that all zeroes is all black, all Fs is all white, CC is more "on" than 99, and EE is just a teeny bit less than full on.

CSS also permits three-character color codes. The same color-mixing is happening there, it's just a shortcut that doubles each character for you. So #ca9 is equivalent to #CCAA99.

Putting this into practice...

#FFFFFF	Turning all three levers full on makes white.
#CCCCCC	Backing them off a little, but keeping them all equal, makes gray.
#000000	Turning them all off: Black.
#FF0000	Red on and the rest off makes red.
#990000	Turning down the red, so that it moves closer to black, makes a darker red.
#FF6666	Turning up the others, so that the whole mix moves closer to white but has more red than anything else, makes pink ("Lightish red!").
#FFFF00	Red plus green (when mixing light) make yellow.
#FF9900	Keep the red, but reduce the green, to make orange.
#00FFFF	Green and blue make teal.
#FF00FF	Red and blue make purple.

So there you have it: An explanation of hex color codes by way of my seventh-grade science class and my high school drama—er, drama department. Right.

The Null Object Pattern: When a slacker is just what you need

I had a challenge that was neatly solved by the Null Object pattern. I'd like to share it with you, so that I can explore the idea and provide a practical example.

Simplifying a bit, I have a Person object, and I need to fill it with details retrieved from an external system. When I started looking at the code, the call to look up the Person attributes took a Person as a passed-in parameter and modified it. That struck me as bad behavior ("Hey! I gave you that so you could use it, but I didn't expect you to change it. Sheesh."). I thought it would be more honest for the method to return information, which the controlling class could use to update the Person object if it chose to.

Let me name the players, to make this easier to follow. I have a class coordinating activities that, in our business context, is called a Translator. I created a Client that makes the actual calls to the external system. Before the refactoring, the Translator would call Client.Lookup(Person). The Client would create a message to the external system, get back a response, and use it to set attributes in the Person.

I changed Client.Lookup so that it does not change the Person, and instead returns a Response that contains the needed attributes. But if the external system did not have any info to return, should Lookup return null, throw an exception, ...?

Usually the most appropriate answer to this question is to throw an exception. If no info means you're in an invalid state or an unknown state, then it is not safe to continue, and the code should throw. In this case, though, we could continue. We didn't require the info coming back from the external system; it was just handy if available.

So I return null? But that means every time I call Client.Lookup, I have to check whether the Response is null before I use it. And so does anyone else who might be calling it in the future. It seems disingenuous for a method to say, "I'll give you a Response, but I might actually give you an empty bag. I hope you've guessed I might do that and planned accordingly."

   12 public void DoFancyBusinessSteps(Person person)

   13 {

   14     Response response = client.Lookup(person);

   15     if (response != null)

   16     {

   17         person.Address = response.Address;

   18         person.ExternalSystemId = response.ExternalSystemId;

   19     }

   20     //More stuff based on the Person...

   21 }

I'd rather return an object that is safe to use, regardless of what answer we got from the external system, and is helpful if we received useful info. This is the Null Object pattern.

I created an IResponse interface that exposes one method, Update(Person). Next I created two implementations of that interface, a Response and a NoDataResponse.

   12 public void DoFancyBusinessSteps(Person person)

   13 {

   14     IResponse response = client.Lookup(person);

   15     response.Update(person);

   16 

   17     //More stuff based on the Person...

   18 }

Response.Update uses its fields to set properties on the Person (with a method name that clearly states it is doing so). NoDataResponse.Update quietly does nothing. This allows the Translator to ask the Client to look up info about the Person, and ask the resulting Response to update the Person.

   21 public class NoDataResponse : IResponse

   22 {

   23     public void Update(Person person)

   24     {

   25     }

   26 }

I like it. As with all good tools, it's prudent not to over-use it. If quietly doing nothing would leave the Person object in a bad state, so that it blew up or corrupted data when you tried to use it later, then don't use the Null Object pattern. Throw an exception instead. The Null Object pattern is handy when you want to return an object that can do stuff in some conditions and will be harmless in other conditions.

Follow-up to the Retrospectives Workshop

My co-facilitator Suzy wrote up her reflections from the AgileAustin retrospectives workshop, where she shares more of the great insights that came from the participants.

Retrospectives: Collaborative Improvement

Suzy Bates and I facilitated an AgileAustin workshop this morning called "Cheaper Than an Off-Site: How to hold effective retrospectives that improve team collaboration and performance." It was absolutely a blast, from planning through delivery. A benefit I didn't anticipate (but should have) is that I learned a lot, myself. I'll share some of those epiphanies here.

If you were to ask me what one thing a team could do to improve its delivery of great software on a predictable schedule, I would say: hold effective retrospectives. A retrospective is a regularly recurring discussion where the team reflects on how they work together, and what they will change in order to get better. The end of a sprint, right after the demo, is a good time for this.

We presented the following as the key ideas:

1. Safety
2. Diversity of viewpoints
3. Collective ownership
4. Structured discussion

Being a facilitator for the workshop was a bunch of fun. Collaborating with Suzy was excellent—meshing our two approaches really enhanced the content, as I brought the philosophy and she brought the practical hands-on exercises, and we kept each other moving and making progress on our preparations. If you're tempted to lead a workshop but daunted, find a teammate.

The audience participation was even richer than I'd hoped. People enthusiastically contributed, leapt into the exercises with gusto, and shared some striking insights. I learned neat stuff. Here are some highlights:

• Rotate who holds the role of retrospective leader (or sponsor). That brings fresh ideas and spreads the sense of shared ownership.


• When a team member expresses dissatisfaction (for example, through a team satisfaction histogram), sometimes it is appropriate to acknowledge it without delving into why and root cause and solutions. If team safety means I can say how I feel and that's okay, then I should be able to say how I feel without getting interrogated about why I feel that way.


• A bunch of "went well" items without any "needs fixing" items might indicate a lack of team safety. In today's exercise, our sprint teams barely knew each other, so they wanted to be polite, and so they were very positive in their reflections. When you're comfortable with your team and trust them, it becomes easier to talk about areas for improvement. I'd view a series of "everything was great" sessions as indicative of a lurking problem.


• Affirmative Inquiry is a philosophy/strategy worth looking into. It replaces, for example, the negative "why is this broken" by changing it into a positive "what was successful in the past that we could apply here."


• Book recommendation for Jim Highsmith's work (probably Agile Project Management?).

If you attended the workshop: Thanks! It rocked. If you weren't able to, keep an eye out for future AgileAustin workshops. They're announced on the AgileAustin email list, so sign up for that. If you don't live in Austin, well... nanny nanny boo boo.

Quantifying Benefits on Refactoring Work

When last we talked about estimating and prioritizing code maintenance, we'd left it as an exercise for the reader to devise a method to compare the relative size of the benefit from two different refactorings. In other words, you can work on A or B; which one is likely to give a greater benefit? I've had an idea for how to do this. It even includes some satisfying math.

Start with the premise that, when estimating the size of effort, it is sufficient—nay, preferable—to compare values in an abstract unit ("story points") that does not map directly to any real-world concept (such as "hours"). When you try to estimate effort in a real-world unit, people get distracted by (hung up on) the wrong details. Better to use an abstract unit that lets you compare the relative sizes of two efforts. Then you can prioritize them ("Let's do the smaller one."), and over time you develop a predictive measure of how many units your team can deliver. Can we create a similarly abstract yet useful unit for comparing benefits?

You undertake a refactoring because you want to make the code better. The benefit from this work comprises two pieces: how much you're going to improve an area of the codebase, and how important that area is. Your impact will be made up of how much "betterness" you can impart, and how much the betterness will matter.

You've probably had a similar experience: You find an area of the code that makes you frankly itch to improve it. You could dramatically increase its beauty. But it's not really used in very many places, and business needs hardly ever drive you to change it, so its beauty or lack thereof is actually rather insignificant. On the other hand, there's a class that makes you queasy every time you have to interact with it, but it's used everywhere, so changing it would be a huge, risky undertaking. It stays ugly, despite being so important.

There are a number of intuitive and emotional influences in those decisions, and they interact with each other in additive and multiplicative ways. This is a good place to apply some rigor, to get the emotions out of the way and compare options more objectively. You apply a similar rigor when you tackle a difficult decision by actually writing down the pros and cons in two columns on a piece of paper, so that you can see how the two sides stack up. So let's apply that to comparing the possible benefits from two refactorings. We only have time to do one, so we're trying to decide which one to do.

Consider a questionnaire, with pairs of questions, asking about what the code might be like after you're done.

1. Future proofing:




1. How much easier will it be to change it the next time?


2. How often do we get asked to change this area?




2. Regression proofing:




1. How much better will our test suite be able to prevent defects in this area?


2. How business-critical is it that we don't introduce defects in this area?




3. Avoiding risk:




1. How likely are we to succeed without creating problems?


2. How tolerant is our business of risk in this area?




4. Improving satisfaction and increasing velocity:




1. How likely are we to reduce tech support incidents by this work?


2. How many of our tech support incidents can be attributed to this area?

And so on, with questions that are specific to your own team. Collaborate with your team to create the questions, so that they represent the team's decisions. Note how a pair of questions covers how much improvement and how much that improvement will matter. Also see that for each question, a more emphatic answer is a good thing. For example, the avoiding-risk question asks how likely we are to succeed, not how risky the task is. Questions are phrased so that, the more you say "Yes, a lot," the more that's an endorsement in favor.

Now, depending on your bent, this next bit will remind you either of a prioritization matrix or a Cosmo quiz. Nevertheless, for each question in your questionnaire, answer a 1, 3, or 5, to represent "barely," "some," "a lot." Then multiply the coordinated a's and b's and add those up: (1a * 1b) + (2a * 2b) + (3a * 3b)... In this way, you represent the multiplicative relationship between How Much Better and How Much Does It Matter.

We need a unit for these scores. I'm thinking "bunits" (BYOO-nits) because they are a unit of benefit and of beauty. So if you have two refactoring tasks on the table during your sprint planning, and Refactoring A has an effort of 13 story points and a benefit of 17 bunits, while Refactoring B has an effort of 8 story points and 23 bunits, you can lean towards choosing Refactoring B. As with all matrices of this type, if that decision completely flouts your intuition, then discuss it with your team—maybe your intuition can be calmed, or maybe the questionnaire is failing to cover an important aspect of your work and needs some additional questions.

The real benefit of refactoring is proven only over time. Keep previous bunit estimates in mind and use those in your comparisons and trade-offs when selecting refactorings to undertake. Add this technique as another tool to help you understand the parameters of your decision, but never to override your own good sense.

This is a technique for quantifying the benefit of work that does not have a direct dollar ROI. Why quantify benefit, especially in a unit that has no analog in the real world? Two reasons. First, if you're going to prioritize your to-do list, every item needs some sense of effort and some sense of reward. It just makes sense to do easy things with lots of benefit before hard things that barely matter. Second, asking yourself questions like the above imparts rigor to your decision-making process. We are seekers of beauty, and want desperately to clean up whatever icky thing we looked at most recently. Surveying the choices and comparing relative benefits prods us to make sound business decisions, instead of scratching an itch.

The Trouble with Technical Debt

This article is not about the perils of accumulating technical debt, nor the challenges in paying it down. Instead, it is a call to action to the developer community that we change the way we talk about scheduling technical debt.

It's a constant sore spot and the source of many arguments between developers and product owners: How do you make time for refactoring? When do you pay down your technical debt? I say we developers need to change how we make our proposals.

We ask our product owners to prioritize the backlog: to attach a business value to each user story and put them in order. Then we provide a size estimate for each story, indicating its relative cost in time and resources, and voilà: a prioritized list of requirements with a cost and a benefit for each.

Then we propose investing some time in cleaning up a lurking problem. The work will improve our velocity in the future. By how much? A lot. And how long will it take? A while. So please fit this chunk of work into your carefully prioritized backlog.

You see what we have here, folks: an ArgumentNullException. The product owner has sorted a list of objects based on their cost and their benefit, and then we try to place an object into the list with an undefined cost and an undefined benefit. No amount of arguing is going to make that work.

The first counter-argument I receive from folks is that the business should trust us or, from the more progressive thinkers, that we need to earn the trust of the business. Um, perhaps. But imagine you were the person prioritizing your own list. Even if you trusted your own motives perfectly, how would you prioritize an item with unknown cost and unknown benefit amongst a list of items with known costs and benefits? And that's assuming perfect trust; I'm skeptical of our discipline to admit that substandard, icky code can be good enough. Developers (the good ones, anyway) have a strong desire for elegance and simplicity.

The second counter-approach I hear is timeboxing: allocate a fixed amount of time to refactoring and only spend that much time. That fills in a value in the "cost" column, but it does not address the undefined benefit. Also, can you think of a scenario where you've undertaken a significant refactoring, the clock ticks over, but you're not yet in a stable state? You either roll back the changes (and realize zero benefit), or muscle through (increasing the cost)? For the timeboxing approach to honestly reflect your cost, you must work with the discipline to make many small, beneficial changes, and stop when the clock runs out. Are you up for that?

Speaking of size, be sure to consider the testing cost. Technical debt accumulates in the areas folks are afraid to change. Those are usually business-important, application-spanning areas. Your refactoring will likely touch many features in the application, warranting thorough regression testing. How good is your automated test suite? Be responsible about how much testing you'll need, and be honest about how much time it will take.

Okay, agile developer community. If we're going to get technical debt work and refactoring into a sprint, we need to apply the same rigor that we ask from our product owners. Cut the work into a discrete unit. Write acceptance criteria so you'll know when you've finished. Make some kind of estimate of the benefit; talk with your teammates about how you might quantify such benefit. Using the acceptance criteria, estimate the complexity and size, same as if the work had been requested by your product owner. Observe and reflect on the predictive accuracy of your cost and benefit estimates to improve your estimates in the future. Start conservative to build experience and credibility over time.

Most product owners are happy to invest time in making the product more stable and making the team faster on future features. We need to give them estimated costs and estimated benefits so they can fit that work amongst other business priorities.

Organizing Ideas with Concept Maps

I love concept maps as a way of explaining a topic. (Here's an example, capturing what I learned at a KaizenConf session.) If you're a visual thinker, you'll definitely want to check this out. If you design UIs, this is also of interest.

The way I use concept maps most often is exploring and explaining a concept to myself. The act of drawing the map sorts my ideas visually, lets me hang new information off logical hooks, and gives me a picture to visualize when I want to recall the info later. (If you've talked with me about F# and watched where I gestured, you've seen that OO ended up on the left side of my map, and functional programming was right of center.)

CmapTools is a free software application that makes drawing maps intuitively easy—better than paper, because you can move concepts after you've fleshed out more of the landscape. And I have a strong preference for paper for brainstorming and thought-capturing, so that's saying something.

I like it not only as a tool, but also as an example of usability. It's so low-friction because you trigger actions (creating a concept, making a connection) right where you're already focused, in the work area, not in some menu at the top of the window. Click-and-drag from an existing concept to create a new concept and connect them; then type, click, type to enter the labels on the connection and the concept. I admire CmapTools for its non-noisy GUI—and of course I love it as a user because I can create a map fast enough to not lose the thread of my thoughts.

The example linked above is cool in another way: It's on a wiki where participants at KaizenConf are creating the conference proceedings. Once you go self-organizing, baby, you'll never look back.

Oh, I needed that.

So the thing about mind-expanding, discussion-rich conferences is they can leave you feeling a little overwhelmed with how much more you have yet to learn. At the end of the day, I wanted a cup of tea. The aphorism-inscribed flag on my teabag said:

"Keep up."