Showing posts with label Design. Show all posts
Showing posts with label Design. Show all posts

Monday, September 30, 2013

A practical UI note on the order of input elements in a form

Input elements in a form are usually arranged in their natural ordered, that is: an item that seems to come naturally first would come before another one which seems more naturally to be second. This is of course subjective, but most people would agree that First Name should come first.

Recently I got a feedback on a form, sent by a heavy-user using the specific form many times a day. His request was simple, yet I've never thought about that before. He was asking if we could be kind and helpful to reorder some of the input input elements in the form, so items that require the keyboard would be in one group while items that need only the mouse, such as check boxes and radio buttons, would be separately grouped on their own. This would allow him easier and quicker fill of the form, he said.

(One can argue that the easiest and quickest way to fill a form is by using only the keyboard. But it appears that this user, as probably many others, is good with the TAB key to move between elements, but he is not aware or not keen of using the arrow keys for navigating between radio buttons and space bar for checking or unchecking a check box).

In order not to break the natural order of things (keeping first name first, and gender male/female reasonably up in the form) the grouping should be done in areas of the form, which comes to my new practical note to be phrased as:

Try to avoid too many switches of keyboard input elements to mouse input elements, if those can be naturally ordered into reasonable sub-groups to avoid the switch. This would allow a more rapid fill of the form.

Monday, September 20, 2010

Resource Files

Programs interact with a user in many ways.
They write things to a screen, send messages over the network, say things aloud. And more.

In most cases, except maybe for debug logs, the string conveyed to the user shall be edited, and in some cases maybe even translated to other languages.

It's pitty to still see today modules that interact with a user, without using external resource files. Guys - how do you want someone to edit your lovely messages into something readable? and translate it into Swedish? or Yiddish?

The technical way of how to use resource file is a very old trick. The problem is that in the early days of a project, this is not the top prioirity (that's wrong, guys! the price at the beginning is very low!). The problem is that when it does become relevant, the code is full of strings in so many different places that it's a nightmare to do something.

Things to do on the first day when starting a new project (don't postpone it to "later"):
1. Use good logging mechanism (exiting one, don't invent the wheel)
2. Use automatic build mechanism
3. Use a resource file
( -- do you have more - please add as a comment!)

Well, wait I have one more - have a defined API (slash protocol slash wireframes) for the modules you are developing.

Thursday, June 3, 2010

... and the UI is also going back

Following my last post on concurrent processes, my good friend Effie Nadiv noted that the UI is also getting backwards.


Back in the old days, Lotus 1-2-3 had a menu line that was not opening to overlay your main screen but was instead changing the menu line each time you make a menu selection. One can argue that this is not optimal, but I remember it as something very useful. Today in some cases you find yourself struggling to open the sub-sub-sub-menu to select something, trying not to close the entire thing before you make your selection.

It becomes also a common practice that any new dialog or window may hide previous ones, extra info may hide the main data etc. Effie argues that it all becomes from the philosophy that the application may do whatever it wants. Restrictions would heart creativity and we don't want that. So you have creativity in the new versions: my new version of Babylon has a fancy UI, ignoring the fact that it is not working, and the old one with the standard Windows UI was OK, it's a real charm. The new office is a nightmare, after you got used to something. Any new version of a SW tries to justify itself with a new fancy visual design which you don't want. You just want it to work.

Tuesday, September 22, 2009

Frameworks -- Explicit and Implicit Wiring

In any new project, there is that moment when you are reflecting whether a group of classes belong to the package "core" or "utils" or "framework", or whether you need all these three altogether.

The difference between utils, framework and core should be simple. Utils are the basic functions needed by everyone, mostly unrelated to this specific project. They are all stateless by definition, simple input and output, with no dependency with the project's structures. Utils can always be easily tested as stand alone. Core is the basic stuff. The stuff you would direct a new developer to learn first. It is project specific. It may include the basic types relevant for this project, interfaces, enums, project's basic exceptions, etc. Make sure to avoid making it a trash can. It's not the address for things without a context.

Framework is the tricky one of all three. As opposed to "utils", the role of "framework" as suggested by its name is more complex. A framework is a piece of behavior interacting with other code to represent a real, concrete, runtime behavior. Usually, even if built specifically for this project, it has some generic characteristics, it is written in a way that could be extended, or used in the future in other ways that we don't see currently. For this we use design patterns like strategy, command, visitor, and in fact almost any that you can think of, to create some kind of "dynamic behavior", or "dynamic wiring". Which means that the framework describes a behavior, but not entirely, only an exact usage can describe an end-to-end scenario. This is why frameworks are best explained with an example (while utils can be explained by what they simply do).


There are good frameworks and bad ones. EJB in its first versions for example was horrible (some don't like it till today, a first bad impression is hard to fix). JDBC is a good framework. Java-Servlets is a good framework. What makes good frameworks good is that people find them easy to use, they save development time compared to other alternatives, and you would usually find over time very few versions of the same good framework (and the new versions would be fully compatible with old code). Of course the question is how to achieve this simplicity, real contribution and long-run future compatibility.


When designing and implementing a framework, occasionally you want to make life easier for the user by doing something automatic for him, let's say pass the value of some field into another field with a relevant name convention -- thus the user doesn't have to write a single line of code! There is this trick in the framework which does it for him. Let's call it "implicit wiring". Alternatively, you may expose to the user a way to acquire the value and require him to pass it explicitly by writing his own code. Let's call it "explicit wiring".


In some cases the difference is not so obvious. Suppose you have a controller which may implement many kinds of behavior, if not implemented then a default behavior is used by the framework. When the number of different behaviors of this controller start to inflate, things become a bit obscure, unreadable, thus maybe "implicit". A better approach would be to break the controller to different interfaces and allow the user to implement the interfaces representing the relevant behavior for him, thus checked by the compiler that no method is accidentally left out, more readable and "explicit".


This discussion came out recently with my team member Effie.
We had a reference between two UI elements: "table" and "toolbar". I suggested that if "table" doesn't declare on its referenced counterpart "toolbar" then we will assume by default that it relates to a toolbar with some predefined name (e.g. "toolbar"). That way, I said, even if the user forgot to give a name for his toolbar, things would work nicely.

Effie's reaction was a bit frightening. (Well, not for someone who knows him). It is common in our work environment that a worker shouts at his boss. Which happened in this case. "I'm not working this way, if you want such a framework leave me out of it", was the part I can quote. Of course when he chilled out came the explanation. Implicit wiring is the base of all framework sins. I like such semi-emotional semi-professional reactions! And he was totally right. Think of someone trying to understand how the framework connects a toolbar to a table. And if he wants to add now another table and toolbar how can he do it? True, there is still the explicit way of referencing by name, but once I entered the implicit way, most cases would be using the implicit format which makes the explicit less known and less documented in examples. Also, implicit wiring tends to break over time, as at some point it may collide with something else and break old code. On the other hand, if you allow only the explicit way, all examples would present the explicit way, code would be always more simple to understand and maintain, and less prone for future incompatibilities. Even with the costs of higher efforts in the first implementation, explicit shall win.


Frameworks in their nature do things behind your back. Try to narrow this behavior as much as you can. Make things explicit as much as possible. Less to explain and document and more for your framework future compatibility.


Write? Rewrite? Use? - Thoughts on shaky frameworks

Java is a great language. A great framework, tool, environment, libraries, all of that. From the very beginning the designers of Java thought of almost anything. Well, almost. ResourceBundle didn't support UTF-8 till Java 6! A few bugs were opened on that during the years (4093632 from 1997, 4221013 nicely written, 4749531 begging, 4919638 and 6204853 giving a final attempt, probably missing some). But it took a long time for someone to listen.

Were they drunk those guys? localization with support only for ISO-8859-1? are you nuts?

Yes, you could use escaped unicode (like '\uXXXX'), but it's not readable. Yes, you could use a UTF-8 file and escape your unicode as part of your build process (native2ascii). Some IDEs (netbeans) volunteered to do this automatically for you. But this is still bad.

Luckily for us, in Java 6 you can construct a PropertyResourceBundle with a Reader, thus you can create a Reader based on UTF-8. Or maybe not so luckily? The ResourceBundle.getBundle still works the old way, you cannot ask it to use UTF-8, so they hacked only half way - what the point? (Yes, you can use the Java 6 ResourceBundle.Control class to control the creation of your bundles but it's so lame. I implemented it and it works, but amount of code needed for such a simple task is unreasonable).

Here comes the question: should we use this problematic framework or write our own implementation? After all, it's not rocket science.

Usually I tend to be very careful with suggesting "write your own version of it". Our development instinct is usually seeing the flaws in some existing implementation, convincing our boss that we must write our own new version of it. In many cases our new version misses some important parts that the preexisting implementation already handled. In some cases the drawbacks that we saw in the preexisting code are in fact design decisions required in order to deal with scenarios that we don't think of or ignore and may tackle us later. So when I do see some existing commonly used library I'm very careful before I decide it's not good for me.

I found this suggested implementation. Seem much easier than the way to do that with the bone thrown at us with Java 6.

Still, might be not so bad idea to implement the entire thing, load of resource bundle, by myself. I still hesitate.

Sunday, April 12, 2009

Wicked Problems

Wicked problems in software design are problems that tempt you into a certain solution or design that seems reasonable and easy but turn out to be holey as a leach.

Mature developers and software architects know how to avoid wicked problems. Managers with lack of technical background may fall into such traps without even noticing and without realizing the trap even in retrospect, you may find a manager who would be very proud of a solution his group created for a wicked problem, investing in it a few man months, without seeing other alternatives of avoiding it or implementing it a bit differently with much less effort and side effects.

Straight solutions for wicked problems tend to be not only costly for implementing, but also for the long run, as the stitches sewed to close all holes tend to get unstitched, torn open.

Let me take you through a very small problem that I was dealing with, and turned out to be wicked.


Some background. In web applications we need occasionally to get info from the server according to user selections without turning to a new page. This is called an AJAX operation. There are several frameworks for supporting easy implementation of AJAX calls. One of which is YUI (Yahoo User Interface), which does on top of this all sort of other great things, supporting similar web experience on different web browsers.

YUI has a component for AJAX auto completion. The component is quite powerful and allows selections ranging from simple ones like this:



to more complicated, as this one:



In YUI the selection made is entered into the input-box and this is the information sent back to the server. We wanted to add the ability to send back to the server an ID instead of the selected value itself. This is useful since in many cases we want to present to the user meaningful text while the server really needs an ID. And we wanted it to work also for the multi-select version.

The solution seemed to be simply to add a hidden field and put the IDs there. The server would of course need to send in the AJAX reply the text to present in the list and input-box, as well as the ID per each entry. Making it part of the JSON reply is simple. Now, every time the user makes a selection we can add the ID into the hidden field, even for multi-select.

Simple and easy. We even found a few implementations like this on the net.

But this is not enough...

Since the user types his selection, he may type a selection without selecting (clicking on it) from the suggestion list. The user may also delete things after selecting them and then the hidden field needs to be updated. He may also retype characters into a selection made already, thus changing it to another, legal or not.

One thing came to our mind is that this feature needs to go with "Forced Selection" which means that the user cannot add things into the input-box without selecting them from the suggestion list. This may solve some of the problems. But not the deletion problem, we still need to take care of user deleting a value from the input-box. The only way to tackle the deletion problem is by populating the IDs hidden field only when the user leaves this input-box (when the focus is lost, i.e. in the "onBlur" event). Then what we can do is to loop through all values in the input-box, add a relevant ID for each in the hidden field, and display a warning for illegal values (for which there is no matching ID). The problem now is that at this point we may not have all IDs, so we need to go back to the server, in an AJAX call and ask for the IDs. And the values in the input-box must be unique, that is: each must represent exactly one ID (there cannot be two John Doe).

At this point we realized that we are going to work hard for a solution that would not bring much value to application writers, as they would need anyhow to implement a function on the server side for replacing textual values for IDs, and those textual values must be unique. So why don't just post the textual values back to the server as is, exactly as implemented originally by YUI.

Well, there is one reason for the hard work. And it is supplying warnings to the user while he types and not following post back. By checking whether all textual values has legal IDs we can warn the user for illegal values before posting the form. But then, one needs to decide whether this worth the investment, and whether it can work well.

We came to the conclusion that the people at YUI knew what they were doing. It is way too tricky to post back IDs. No, it's even more than that. It's wicked.

Now, we invested about half a day in investigating the problem and thinking of solutions, and then eventually decided to avoid this implementation. How many of us would do the same after investing a week in investigating?

A wicked problem is usually a problem that you'd better waive, avoid, abandon. Suggest other ways of doing it. Replace with another feature which is easiest to implement. The efforts of solving the wicked problem do not justify its value. Yes, a wicked problem is sexy, if you solve it you can become a true hero, it makes out a really neat feature. It is courage and experience, needed to realize the real effort for these wicked problems and to admit they do not worth it, even if some time was already invested in analysis and investigation. Or, to find the easier design, almost fulfilling the wicked problem, achieving most of the goals with much less effort.


Monday, March 16, 2009

Software Factories

Before the industrial revolution most of the products were made by hand, crafted. Is software manufacturing today more like a confection (ready made clothing) or more like "haute couture"?

The term "Software Factory" was created for describing the possibility of getting software requirements and sending them into a "factory" for manufecturing. (Do not mix that with a Microsoft technology with a similar name).

The challenge is that with software, customer needs may be very complicated. Can we just send the requirements into a "Software Factory" and get it done? (This in some way contradicts the idea of constant communication embedded in Agile Development.)

Think of airport control system that needs to address all kind of airports and equipment. Think of banking software that shall address different banks and communicate with all sorts of external interfaces. Can we create modules that are generic enough so that customization for specific customer needs can be done by cheap work force and without too much complications and investment?

Most software projects cannot be cloned. There is no customer that resembles another, requirements are different and the "physical" legacy environment is not the same.

Closets are also not all the same. Each customer may have different specific requirements. Nevertheless, most carpenters manage to stay scalable and address specific requirements by setting standards, such as several available sizes (you can order a closet of 2.0 or 2.4 meter height, however, 3.0 meter height would be a special order, would be processed uniquely and priced accordingly) and several available woods.

To achieve the ability of creating software as in "Software Factory", we shall:

  1. Narrow the options and alternatives. State clearly what can be built as a standard and what is a special order.
  2. Externalize a clear API
  3. Insist on always getting clear requirements before starting (did you see a carpenter starting to work on a closet before having all measurements?)
  4. Have core modules, easy to customize for very specific needs, with hooks and plug-ins for adding specific functionality
  5. Create a very strict and close way of customizing the product, allowing it to be done by cheap work force. Always prefer customization techniques which require less thinking. Customization shall not be art, it shall be very technical and strict, preferably with clear instructions.
  6. Both the core module and the customizable product shall be easily testable, each on its own.

I had a debate recently on whether the preferred technique for rendering raw data into HTML is JSP with Taglibs or XSL. Though XSL is very powerful and can do anything with raw XML at hand, I argue that a set of strict Taglibs with the instruction not to use Java code inside JSP makes it much easier to make this task in the mode of "Software Factory". In oppose to XSL, which is in some way an "art", using a strict set of predefined Taglibs is something that is much more narrowed, cannot handle all cases and special requirements, but can certainly provide most needs and most importantly, can be done by almost anyone, given clear requirements.

We are already in a period in which most organizations cannot afford having their software be "haute couture", they must settle on confection, ready-made, with some adaptations. Most software companies who would still manufecture their organizational software products as "haute couture" would not survive, unless in very specific and unique domains. When software becomes a commodity, like a cheap chip, the only way to produce it is in a "Software Factory" model.

Friday, March 13, 2009

Real Life Architecture

When designing a system one shall think of all possible scenarios and error cases. Ignoring a possible scenario may lead later to all sort of problems, ranging from crashes to logical errors (e.g. fulfilling a financial transaction without finishing the order process, so the customer is debited but would not get any product).

One thing that we shall bear in mind is that listing all possible scenarios does not mean implementing a solution for all possible scenarios. There are error cases that are quite rare or not-so-rare but very difficult to handle, maybe even require a whole different design approach. A possible solution may be to log the problem to a specific database for manual handling, or for a later amending batch operation. Such approach can save a lot of the hassle during all stages: design, implementation and maintenance.

I may rephrase the above rule: listing all possible scenarios is a MUST, however, implementing a solution for all possible scenarios as an integral part of your system is probably not always the best solution.

Usually implementing a fully-blown solution for rare cases doesn't really work, as it is not tested enough for all variants and nuances of the exact scenario, and when the rare cases do happen you see that some modifications shall apply. Taking the treatment of rare special cases outside of the system, to either manual or batch operation may thus be a wise thing to do.

I call this "Real Life Architecture" based on the famous article by Gregor Hohpe Starbucks Does Not Use Two-Phase-Commit, which appears also as a transcript at Joel Spolsky's The Best Software Writing I. Gregor argues that in real life we often use asynchronous messaging without worrying too much about error scenarios, which we do deal with when happen, in somewhat batch way. As an example Gregor goes through the ordering mechanism at Starbucks, its simplicity and efficiency.

Wednesday, December 17, 2008

Module Separation

Module separation is one of the oldest tricks in software engineering. As it is too complicated to attack a big problem, we split it and attack it in pieces. The pieces should eventually work together. We don't want to have two teams digging a tunnel from two sides of the mountain, missing the meeting point. In the tunnel case you get two tunnels which may have some value, with software you will just have a dysfunctional messy system.

The engineering task, some would say the art, of defining the modules and the interactions between them, is crucial for the success of the system. Do we need our modules to be stateful? Do we want synchronous or asynchronous communication? What would be the messages language between the modules, would it be programming API or a communication layer? On top of which protocol the messages would travel? And on top of all, which modules should we define? and for each module, which modules it shall be aware of and which it shall be totally agnostic and unaware of?

Usually we would like the communication between modules, i.e. the public interfaces that a module should expose, to be as little as possible. Operations or sub-operations that require much communication would be preserved in the same module while operations or sub-operations that require lesser amount of communication can be split. We should also like to have some hierarchy between modules so that not every module would have to know all the others, preventing cyclic dependencies is usually an architectural requirement.

So, what is the definition of a module?

Trying to create a definition of a module, or even better, a subscription, is not easy. Recently I was attending a session by Rick Kazman the co-author of "Software Architecture in Practice". Rick referred to this question, defining a module as "the set of tasks belonging to a unite topic, managed and built by an independent team of people." It is interesting to note that Rick's definition focus on the organizational aspects more than on architectural aspects of "what is a module". Rick argues that this goes well with Conway's Law stated by Melvin Conway in 1968, arguing that the required communication between two teams has a direct relation to the required communication between the modules they develop.


Create your own module

A module should have a clear definition of roles and responsibilities, both technical (what the module does) and organizational (who is responsible of defects found at this module). It should have also a clear and concise public interface. A module would usually be deployed as one unit, but in many cases several modules would be deployed as a unit together. Different programming languages would give modules different semantics, syntax and deployment characteristics, yet still some programming languages may not have the notion of modules in the language itself. And, not less important, a module shall be clearly defined as a set of tasks managed and built by an independent team of people.

How to do a 2000 pieces puzzle in a team



Doing a huge puzzle in a big team, does increasing the size of the team assist? Is there a number at which we will have a negative marginal contribution? ("Mythical Man Month"). Can you create "modules" here? This question about puzzle building is inspired by Chris Rupp's talk at JAOO 2008 (see video capture here).

It's a very nice exercise for a management course. I would think of the following design: (a) dispatcher team - goes through the pieces and assign them to the other teams; (b) teams by colors and shades, e.g. Dark Blue team would deal with the sea part while the Light Blue team would deal with the sky; (c) frame team, getting all the pieces that shall compose the frame. Each team is a module, so we have a dispatching module, a few color building modules, by colors and shades, and a frame building module.


In case of resource shortage we can settle without the dispatching team and let the building teams themselves do the dispatching. Number of people will define the separation into colors for the color building teams, but even if we would have 1,000 people we would not define 10 shades of blue, as the interaction between the teams (I got this blue piece but it seems unrelated to me) would be too exhausting.

Shall module definition be influenced by external factors?

We saw in the puzzle example that to some extent, number of available people would influence the number of shade teams that we may define. Expertise and skill set of our resources, as well as their geographical disposition shall also play a role here, but we will leave this for a later post on the relations between organizational structure and architecture.