I hope you are keeping disease from your door and money in your bank accounts.
I'm going to start a series of articles prefixed with "A Good Design" and use it as a mechanism to illustrate various design principles.
To start the ball rolling let's look at a self explanatory design. This is what I mean by "at a glance readable" and the point of the exercise is to remove any question in the mind of the reader of the code as to what it is doing.
If you joined me for my UI Playtime session you would have seen this little control.
It's a color ramp with a mask, and you give it a number to set a color. (Red = Error, Blue = is Off (bg color), Yellow = Syncing, Orange = Unsynced Idling, Green = Synced)
If you've been following my blog you will know I queue up all my UI updates. I could pass the color into the queue as a number. Like this.....
This is poor design, because to look at it I need to know things about the receiving control. That is not scaleable to large projects.
You should be using label constants to give your diagram some more information. So this is better...
Which is fine as long as the comment isn't lying!
The best solution gives no room for interpretation. This the what I want doing and it either works or there is a bug that needs fixing.
Representation of message data and the abstraction of the control setting
Obviously this is a bit more work, but it really pays off at the end of the project.