These forums are in read-only mode. Please see this news post for more information.

New forums can be found here


Go Back   WowAce Forums > Addon Chat > Frameworks
Frameworks Framework Discussion

Reply
 
Thread Tools
Old 01-17-2008   #1
sylvanaar
Legendary Member
 
Join Date: Nov 2006
Posts: 2,876
Default Long Post - But I think it is topical.

Posted without permission, CH5 of "Preventative Programming Tecniques..."


Chapter 5: Over Simplification

Description
When designing objects and interfaces, it is important to keep the design and implementation simple in order to maximize readability, usability, and maintainability. However, the goal of minimizing the complexity of the implementation can go too far, making the implementation essentially useless. Over Simplification comes from a desire to follow proper design techniques, but the programmer takes the wrong approach to this goal. Let us take a closer look at how to spot code that is too simple for the requirements placed upon it.


Symptoms
Overly simple code is more difficult to identify that the overly complex code created by Complexification. This is true in part because complex code should be less common and therefore easier to analyze than simple code. Since the majority of the code on a project should be simpler code, it becomes hard to identify the overly simple code from the correct level of simplicity. On the other hand, complex code tends to stick out and requires only an inspection to mark it as a candidate for being overly complex. So, what are the symptoms that we can use to help reveal overly simple code?

So Simple It Does Not Do Anything
The reason we write code is to accomplish some goal, or at least it should be. However, due to poor coding practices or the inevitable degradation of code over the course of a project, sections of code can cease to perform any useful function. Spotting this type of code serves two purposes. First, it improves performance by removing code that does not need to be called. Second, and more important, it makes the code more readable and maintainable.

What does this have to do with overly simple code? After all, you would not think of extra code coming from simplicity. To understand this, it is best to understand that simplicity does not always mean code simplicity. Simplicity can also mean design simplicity. While seeking design simplicity, it is easy to increase code complexity.

The creation of interfaces and class hierarchies is a common place for this to occur. In the interests of creating consistency in design and use of interfaces and objects, the programmer might be required to introduce code simply to handle the odd cases created by attempts to make all objects equal when they are not. This is generally caused by a misunderstanding of object-oriented technology. Although the design at first appears simple, in practice it becomes more complex and forces the addition of functionality just to maintain the simplicity of the design.

Shifting Complexity
Most applications contain layers of functionality built on top of each other. In a properly designed application, these layers should distribute the complexity as evenly as possible. By assigning the appropriate responsibilities to the appropriate layer, the implementation can be simplified while maintaining a simple interface to the other layers. However, if responsibilities are assigned to the wrong layers, the overall complexity of the code will rise.

One of the most common occurrences of this is Over Simplification in the lower-level functionality of the application. In an attempt to provide a simple base on which to build, the complexity is shifted upward where it becomes many times more complex to implement. This rise in complexity is caused by the differences in data access and the increased communication necessary between layers. This simplification is often accompanied by weakening of encapsulation and abstraction to allow the transfer of functionality to another location in the code. Whether this occurs through design failures or the natural evolution of the code, it is a sign of Over Simplification that should be corrected.



Simply Disastrous
One project developed a very simple interface that was to handle the majority of the work for the application. It consisted of two main classes, and only one of these classes was designed for inheritance. Let us look at the basics of these two classes:





class t_Object {

// ...

private:

// Linked list of object properties.
t_Property *m_properties;

};

class t_Property {

// ...

private:

// Type identifier.
int m_id;

// Owner object.
t_Object *m_owner;

// Next property.
t_Property *m_next;

};
Every instance of the main object would be the same except for the properties that were attached to it. Each property knew only about itself and its owning object. This design was chosen for its simplicity and consistency. In addition, several manager classes handled the execution of specific types of properties.

This simple system quickly broke down as it became obvious that properties were required to know about each other. Because the only way to distinguish the property was through its type, the code became scattered with small cut-and-paste instances of linked list searches for a particular property type. These were accompanied by type cast, introducing even more chances for error. Numerous bugs were encountered because of this originally simple design.

Do Not Touch
One roadblock to fixing Over Simplification can often be a sign of a programmer suffering from that very illness. Because there is a beauty in simplicity, a programmer who creates a simple design and implementation might defend that implementation even if the change will result in increased simplicity for the code as a whole. This narrow vision is understandable from several perspectives. The time invested in writing the code and creating the simple design seems in danger, and modification to it will make the original programmer?s job of maintaining it more difficult.

Nevertheless, these views ignore the necessary give and take required for a team to function efficiently. Making the changes will help in relations and also show a willingness to share in responsibility for the entire application. When you find yourself or another programmer resisting changes to functionality because of a fear of breaking the simplicity, step back and evaluate how the change will affect the simplicity of the code base as a whole. If you end up with a simple low-level implementation, but a horrible mess at the middle level and up, you will regret not moving some of the responsibilities down to the lower level.


Prevention
Over Simplification is prevented primarily in the design stages of development. Once the coding begins, the distribution of complexity is likely to take a life of its own and require redesign and refactoring to fix. This does not mean that there are not opportunities to prevent Over Simplification while coding, just that it is simply less common.



Cure
Once Over Simplification has reared its ugly head within your code, it will continue to cause problems as long as it is there. Let us look at how to remedy the problem to save time and money.

More Sacred Code
Just as programmers defend the code they have written against replacement by outside code when suffering from NIH Syndrome, they also defend their code against added complexity when suffering from Over Simplification. Treating their code as sacred, they will defy reason in their desire to maintain its simplicity. Before you can consider refactoring, you must convince the owner of the code, which could very well be you, to consider the reasons why added complexity to the code might reduce the overall complexity of the entire code base.

As with NIH Syndrome, the defense of code simplicity might indeed be valid. Before ignoring the sacred code of the programmer, you must be disciplined enough to consider all consequences of the proposed change. The objective of a change that increases the complexity of a particular section of code should be to reduce the overall complexity of the entire code base. Resist the temptation to shift complexity to another programmer when it only benefits you and not the entire development effort.

When to Refactor
Over Simplification causes complexity to appear in the wrong areas of the code. As this complexity appears you should consider the benefits of refactoring, whether you are working on it at the time or just encounter it while browsing the code. It is possible to allow one instance of misplaced complexity to rest, if you are reasonably sure that the particular functionality will not be required again. As soon as similar functionality occurs more than once, the complexity should be refactored because the maintenance of the complexity increases substantially for each occurrence. Chances are high that more occurrences of that complexity will continue to occur.

Up and Down
Refactoring Over Simplification in most cases requires the movement of code between layers of functionality (Figure 5.1). In an object-oriented language, this might be represented by movement within a class hierarchy, but it might also involve movement between hierarchies. Do not constrain your movement of functionality by arbitrary language constructs. Over Simplification is a design problem and is not particular to any programming language features.


Figure 5.1: The progression of class complexity over a typical group of classes suffering from Over Simplification. The size of the rectangle representing a class represents the classes? complexity. Once it becomes obvious that one or more of the classes has become overly complex, refactoring can redistribute the complexity to a more maintainable level.
For example, if you find a function in one class that primarily uses access to members of another class, the function should be moved to the class with the members it is accessing. If you see:

class Object1 {

// ...

public void someFunction(Object2 object)
{
int someValue = object.getSomeValue();
int someOtherValue =
object.getSomeOtherValue();

// Do some stuff with someValue and
// someOtherValue that does not use
// any private members of Object1.

object.setYetAnotherValue(result);
}

// ...

}
This should become:

class Object2 {

// ...

public void someRefactoredFunction()
{
// Do some stuff with someValue and
// someOtherValue which are already
// members of Object2.

yetAnotherValue = result;
}

// ...

}
Duplicate code in multiple derived classes can also indicate an instance where the simplicity of the base class is being preserved at the cost of the derived classes. By moving these functions to a single function in the base class, the overall complexity of the class hierarchy will be reduced even though the base class complexity will rise. These, and other refactorings, should be done as soon as they are found to get the most benefit from the redistribution of complexity.

Libraries for Reuse
Future projects can also increase the benefits of refactoring. After your project discovers the proper level of functionality for a module, through experience and refactoring, that module can be separated into an independent library. This lasting benefit of refactoring is often overlooked because of production deadlines and the excuse that you will never use the code again anyway. To be competitive in the modern world of software development, however, rewriting everything from scratch is no longer a reasonable option. Managers are demanding more code reuse, and you could be stuck with old code despite your desire to throw it away. Since refactoring does have benefits for your project and it will save you headaches if you must reuse the code, it is only logical to maintain the simplicity and reusability of the code without concern for future assumptions.


Related Illnesses
Previous contact with Complexification is the primary cause for Over Simplification. After having been on one or more projects that suffered from overly complex design and code, it is easy to switch to the other extreme and attempt to make the design and code overly simple. Instead, a middle ground should be sought to balance the complexity of individual sections of the code with the complexity of the code base as a whole. By seeking to attain minimal and complete interfaces and implementation, you will not be susceptible to either Over Simplification or Complexification.

Just as Complexification causes Over Simplification, Over Simplification is a common cause of Brittle Bones. Because Over Simplification offers functionality that is generally less than complete, it provides a weak foundation for future code built upon it. This makes it important to remedy Over Simplification early in development. Failure to do so is symptomatic of the common illness of Myopia.


First Aid Kit
As was the case with Complexification, very few tools can help with Over Simplification. Collecting the proper level of requirements and covering the necessary design issues will put you well on your way to preventing Over Simplification, and for this, you primarily need knowledge, which is not something that a tool can give you.


Summary
The symptoms of Over Simplification are:

Code that performs no useful function, either by design or through decay, and that is still present.

Complexity that has been shifted from its correct location and therefore been made more complex.

Excessive protectiveness placed on code just to maintain its simplicity.

To prevent Over Simplification:

Ensure that the design, interfaces, and implementation are complete in addition to minimal.

Be realistic and do not make the low-level design too simple; otherwise, you will be missing functionality that is required for the higher-level design.

Prepare for areas of likely change.

To cure the effects of Over Simplification:

Do not allow code to become a sacred cow because of its simplicity.

Add or move complexity when refactoring as necessary, rather than to avoid work or responsibility.

Make sure that functionality is at the proper place and level to minimize complexity.

Consider the possibility that the code will be reused when writing it.





__________________
sylvanaar is offline   Reply With Quote
Old 01-17-2008   #2
Tekkub
Tanuki
 
Tekkub's Avatar
 
Join Date: Feb 2005
Posts: 5,091
Default Re: Long Post - But I think it is topical.

Topical cream?

I'm curious what (or who) prompted this and who it's being directed at...
Tekkub is offline   Reply With Quote
Old 01-17-2008   #3
sylvanaar
Legendary Member
 
Join Date: Nov 2006
Posts: 2,876
Default Re: Long Post - But I think it is topical.

Quote:
Originally Posted by tekkub
Topical cream?

I'm curious what (or who) prompted this and who it's being directed at...
I just read it a few minutues ago, clearly its directed not at any one person, but at the concept of super-simplicity. I thought that this was a good summary of how that can go wrong as well.

i could post the one called "Complexification" if you like - its the oppostite of this one basically - and is also something that many would find familiar themes in. I'm on my way to work, i'll post it if you like when I get there
__________________
sylvanaar is offline   Reply With Quote
Old 01-17-2008   #4
Tekkub
Tanuki
 
Tekkub's Avatar
 
Join Date: Feb 2005
Posts: 5,091
Default Re: Long Post - But I think it is topical.

Post if you wnat, but don't do it for me :P
Tekkub is offline   Reply With Quote
Old 01-17-2008   #5
Bam
Hero Member
 
Join Date: May 2005
Posts: 615
Default Re: Long Post - But I think it is topical.

Thanks for posting it. Very much in line with my view on software development. But always nice to see it put down in writing by someone who have given it some careful thought.

Who is it for? Anyone who designs software really. But library writers in particular since complexity may shift up through the abstraction layers if libraries suffer from Over Simplification.
Bam is offline   Reply With Quote
Old 01-18-2008   #6
sylvanaar
Legendary Member
 
Join Date: Nov 2006
Posts: 2,876
Default Re: Long Post - But I think it is topical.

It applies to almost every developer at one point or another.

Here's something I'm sure you will all find funny. I didn't make it up, I swear.

__________________
sylvanaar is offline   Reply With Quote
Old 01-18-2008   #7
Bam
Hero Member
 
Join Date: May 2005
Posts: 615
Default Re: Long Post - But I think it is topical.

Hehe.

I had to look up the word pecadillo (a small sin). Never heard that before. :P
Bam is offline   Reply With Quote
Old 01-18-2008   #8
sylvanaar
Legendary Member
 
Join Date: Nov 2006
Posts: 2,876
Default Re: Long Post - But I think it is topical.

I want to make that image and text into my signature.

EDIT: How obnoxious looking ROFL
__________________
sylvanaar is offline   Reply With Quote
Old 02-17-2008   #9
Industrial
Amazing Member
 
Join Date: Sep 2005
Posts: 1,517
Default Re: Long Post - But I think it is topical.

I read 6 paragraphs and it was mostly blah.

blah lower level mid level high level of the application <-- "level" == blah.
blah an object class and a property class <-- gz we have tables
blah working in a team <-- most people around here don't, and if they do everone always manages to agree or agree not to and split up.
blah more that I wont even read.

This is aimed at people working in a "corporate" environment to be stimulated to work together and value each others views on the code more.

Having made some of the simplest addons around to do just what they need to I fail to see what I would learn from reading all of this.

Edit: It is also written as if it were a disease, symptoms, prevention and cure in all. I can just see the people that go and read this and then go over their own code to spot the unexistant bad code and "fix it".
Industrial is offline   Reply With Quote
Old 02-17-2008   #10
sylvanaar
Legendary Member
 
Join Date: Nov 2006
Posts: 2,876
Default Re: Long Post - But I think it is topical.

Say hello to Puff and Jackie for me Indy.

__________________
sylvanaar is offline   Reply With Quote
Reply


Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are GMT. The time now is 11:57 PM.