Code Smell : Stringly Typed

This term "Stringly Typed" were coined from codinghorror site here. It is described as "an implementation that needlessly relies on strings when programmer & refactor friendly options are available". Now, have you ever think that you can replace almost every data type, even functions / methods with string? If not, then you can see it here.

Code Smell : Array-based Data Model

In OOP, you have classes to define your data model. Your class can be passed between methods and even other classes as well, making it very flexible to be used, and at the same time still keeping the data structure. It is nice isn't it? Unfortunately, there are a group of programmers who like array-based data model more rather than modeling using classes.

If you find those group working for medium-high complexity projects, quickly demoted them, and exclude them from the socialization. If you find yourself doing the same thing, quickly go to nearest worship place and atone your sin, then begin to start a new life. Is it that bad? Yes it is. Why? Here we go:

What does Clean Code meant to you?

The very basic question

It is the very basic question for middle-level programmer (professional programmer with advanced skill but not yet a master). It has already been discussed maybe for decades in several discussion forums. Some of the source I had found is:

• Stack overflow question
• Linked in discussion - As Technology Becomes More Complex, Design Becomes More Important
• My Linked in discussion

However we arrived to the basic question, what is a clean code actually? This is purely my opinion about clean code.

Is Maintainable / Clean Code is a Requirement to Your Apps?

Dirty code? That is code produced without considering the maintainability aspect. You can consider a code as dirty when there are tightly coupled, using arrays or map-based instead of data structures, or use hacks like global variables. One characteristic of dirty code, is when the application become large or complex, it is hard to extend or modify and prone to error while doing so. Is you application need the opposite (called clean code)? Not every apps need clean code, and here is why.

Designing Systems, the Art and Pitfalls

This article mainly based from this stackoverflow question about designing system. As I have written before about learning by teaching, this is a good example that I see. Even though I had experience designing a system, but I still cannot define exact steps needed to design it. Now I have learned much and able to provide the explicit steps of designing a system, at least from my experience.

The High Level and Low Level Module

In the context of system (application) design, a high level module is an overview picture about how the system interacts with the user, and other integrated system. Since low level module is a detailed picture about how the system interacts between each other subsystems inside. That's it, a system design are divided between two modules.

High Level Module

We need to divide the design to separated modules, because it is hard to design a system without high level (overview of the system) module. High level module are more understandable by the business users. Moreover, there are many pitfalls beside system errors, such as wrong use case scenario and wrong business rule validations. Defining those pitfalls in high level module design is easier and faster. Who does not loves simplicity, faster, and easier job? That's why we should do high level module design.

Taken from my stackoverflow answer, about a standard point-of-sales system that has the following sub-modules:

• ordering
• commiting order
• down payment
• goods delivery
• return

Here is the steps of defining high level module design:

1. Define the standard use case between user and systems
2. Pour the use cases to some collaborated diagram such as rich picture (or anything familiar)
3. Define the exceptions use cases. If the exceptions can be defined easily, put it immediately to model. If not, mark the model with the case exceptions to be further discussed with business teams. Some use case exceptions can be changing committed order, changing committed order after down payment, cancelling payed order, goods out of stock, etc.
4. Iterate the process. Usually step 3 can become step 1 (the exception can / will be another use case). For example the changing committed order can be a use case, since the change of occurring is high.
5. When the 3rd is completed without additional use case exceptions (all use case has been handled), usually I add value-additional operations.
   Those operations can be notification (email / on-screen), historical data maintenance, reminder, error-handling, etc. Some operations can be another use case as well, so maybe you will need to iterate over to no.1.
   Some example maybe when you get error during down payment settlement, maybe you will need another use case to input the down payment data manually. Or maybe you will need to maintain reminder system in another system.
6. Move to low level model

Well, each point can be separated as another discussion.

Low Level Module

Low level module design, on the other hand gives more detailed view in the systems and it shows how each of the subsystems work between each other. Many times, low level modules are overlooked by the management because it is far very faster to immediately begin to code than creating the low level module. Then what is the benefit of low level module design?

These are the benefits of low level module design that is often overlooked:

1. It can act as a documentation
   Class diagram, database design, state diagram, flowchart, sequence. Everything can be taken as a technical documentation or "blueprint" of the system. Is it needed? Yes in most cases, usually in first step of debugging
2. It catches pitfalls, errors and exceptions early
   Most of the time error and exceptions are being caught during integration testing. When during testing and find some of the error, you will review the general process of the system. At that time, it is too late because your code already been constructed with your database structures
3. It design your code base clean
   Little hacks and tweaks are sometimes (most of the times) done to fix something during the testing time (see point 2). Having a low level module, you are forced to define some general structure of your code base, and pitfalls can be avoided early, making your code cleaner and less need to refactor
4. It can be reviewed easily
   Discussing designs with peers using low level module design will be easier and faster, compared to reviewing code
5. It can be used as basis of review and evaluation
   After the code has been completed, you can review the mechanism and structure with low level module design. This will help to find pitfalls or unfinished works earlier (before integrated tests)

Well, there are many benefits but often overlooked by management, because usually they only make schedules with waterfall model. That is, having the development going forward (from design, code, testing, publishing) without handling for exceptions in between (bug fix during testing, redesign during code, etc). And the benefit of low level module in a simple CRUD application seems overkill (even though nice to have) for most management, that in their consideration: "it is okay to have a buggy code published rather than having 40 hours of designing low level module.

Then how do you design low level module? Well, the answer lies in many books, such as UML guidance for OOP, etc.

Programming Idealism, Avoiding Hungarian Notation

Hungarian Notation

From wikipedia, hungarian notation is an identifier naming convention in computer programming, in which the name of a variable or function indicates its type or intended use. There are two types of Hungarian notation: Systems Hungarian notation and Apps Hungarian notation.
System Hungarian is intended to emphasize the variable's type. It is extremely useful in interpret / dynamic language such as javascript or php, and useless at all in static programming language. Especially in compiled oop language such as Java and C#, where data contract and type casting is the major problem, it has no benefit at all.
Apps Hungarian is intended to describe the functionality of given variable, regardless of it's type. As Joel Spoolsky has been explained in his article, there are some variable that is prone to error, even though already has compiled-type checking. One of his example is between unsafe and safe string (encoded html tags for example), in which the type is same but serve different purpose.
The article is posted at 2005. It means it already there for more than 7 years around. Given current ability of compiler and programming language, what can we do to improve the design?

Problem

There lies one and only one problem in Joel's solution, that is the code can still pass compilation phase. As stated by Mark Seeman in his article, faster feedback means less costs to correct errors. Ideally, it is the best when we can get all the system's error during compilation phase, but it mostly impossible for some reasons (such as parsing error or business rule error, in which cannot be caught by compiler). In short, you need to create compile error as much as possible to catch wrong code, rather than getting run time exceptions.

The Proposed Design

Using Joel's example for safe and unsafe string, we need to create a design where we can handle safe and unsafe string which can give compile error. By using C# syntax, as usual for oop language, first I define some classes. The class is for unsafe string.

public class DecodedHtmlString
{
    public DecodedHtmlString(string decodedString)
    {
        this.decodedString = decodedString;
    }

    private string decodedString;
    public override string ToString()
    {
        return decodedString;
    }
}

Simple enough. It gives no benefit but gives you a self-documenting data type. The class represent a html string in a decoded way, and no encoding happen here. Next, for the safe (encoded string).

public class EncodedHtmlString
{
    public EncodedHtmlString(DecodedHtmlString decodedString)
    {
        this.encodedString = System.Web.HttpUtility.HtmlEncode(decodedString.ToString());
    }

    private string encodedString;
    public override string ToString()
    {
        return encodedString;
    }
}

Again, a self explaining class accepting encoded string from a decoded string. Now we want to make both of the classes communicate each other. We have several options such as type casting or static parsing, which is easy enough in C# that I won't explain. In here I will do constructor injection and To type casting instead. For the DecodedHtmlString, we add a constructor and ToEncodedHtmlString method:

    public DecodedHtmlString(EncodedHtmlString encodedString)
    {
        this.decodedString = System.Web.HttpUtility.HtmlDecode(encodedString.ToString());
    }
    public EncodedHtmlString ToEncodedHtmlString()
    {
        return new EncodedHtmlString(this);
    }

And for the EncodedHtmlString side:

    public static EncodedHtmlString FromEncodedString(string encodedString)
    {
        EncodedHtmlString result = new EncodedHtmlString();
        result.encodedString = encodedString;
    }
    public DecodedHtmlString ToDecodedHtmlString()
    {
        return new DecodedHtmlString(this);
    }

Consumer

Let's see from consumer point of view:

string unsafeString = Request.Forms["CUSTOM_INPUT"]; // input from form
string safeString = System.Web.HttpUtility.HtmlEncode(unsafeString); // encoded safe string for reference
DecodedHtmlString decoded;
EncodedHtmlString encoded;

// initial creation
decoded = new DecodedHtmlString(unsafeString); // correct
encoded = EncodedHtmlString.FromEncodedString(safeString); //correct

// type casting
encoded = decoded.ToEncodedHtmlString(); // correct
encoded = new EncodedHtmlString(decoded); // also correct
decoded = encoded.ToDecodedHtmlString(); // correct
decoded = new DecodedHtmlString(encoded); // also correct

// wrong initial creation
decoded = new DecodedHtmlString(safeString); // wrong
encoded = EncodedHtmlString.FromEncodedString(unsafeString); //wrong

// to primitive
unsafeString = decoded.ToString(); // correct
safeString = encoded.ToString(); // correct

// wrong to primitive
unsafeString = encoded.ToString(); // wrong
safeString = decoded.ToString(); // wrong

We got 4 possible wrong code, that is from primitive and to primitive parameter assignment, and for other scenarios it is correct. Now let's see whether we can exploit the data type validation with parameter accepting data type.

public void WriteToDatabase(EncodedHtmlString encoded)
{
    string encodedString = encoded.ToString();
    // doing with encodedString
}

WriteToDatabase(unsafeString); // compile error
WriteToDatabase(safeString); // compile error
WriteToDatabase(decoded); // compile error
WriteToDatabase(encoded); // correct

Now we got 3 compile error and one correct code. If you favor to get a compile error, it is an improvement since now you can protect myself from 3 possible parameter assignment errors. And if you carefully using the two data types instead of passing from primitive string, it will be fine. The only two things that can pass the compile error is when casting to primitive, or from primitive.

But hey, isn't most of the operation (at least safe and unsafe string) is using primitive type? If we take account Response.Write and Database operations, it is very clear that most of the critical operation is using primitive type. (even for url, etc). Moreover, we add 2 more classes for this design.

Conclusion

We can get the design where we will receive compile error instead of run time error or buggy code. However, we still cannot get one hundred percent buggy-code free with this design, and most of the operations are error-prone here. Additionally, it introduces two dependent classes as well, making it more tight coupling.

In the end, it is still the framework's support that do the decide. If the framework support the Encoded and Decoded datatype by default, and suggesting you to use the datatype instead of primitives, maybe it is worth it. However, with current framework design, it is very unlikely for this design to give decent benefit.

Not All Architecture is Fit for Your Apps

I had an interesting discussion over stackoverflow with L-Three in this question. I realized that it is quite an interesting situation there, so I think it need to be blogged. I'm not yet experienced enough in Dependency Injection, so my statements may be mistaken though.

In short, he is advising to use a well structured architecture. That architecture is using some several good techniques, like dependency injection and comand-query separation. Ad a moderate programmer, I can say that the structure is good, clean, easy enough to test and extendable. But I don't like it. No, not because the design is good, but I have some conditions where the architecture can't be applied.

Interface Programming: Entity Wrapper to Handle Dynamic Source Object

Background

During working with legacy code, I have found that many people used DataTable/DataSet instead of strongly typed objects. They are using some code like

string id = row["id"].ToString();

instead of

string id = request.Id;

It is becoming a maintenance hell because of several reasons:

• I do not know the data type from database, so I need to debug into database procedure
• I do not know whether the data is nullable or not, again I need to debug into database
• When I need to change the data type, I need to search for every implementation, change it and make sure it does not break 

And last but not least, if I want to make enhancements or modifications, I have been faced with 2 options:

• Keep  the same programming style, using the DataTable, with the risk that you add another more maintenance hell object
• Refactor it, with the risk of breaking is higher

I want to use Dependency Injection (DI) for my further development. Lack of strongly typed entities are of course prevent me from using DI. So I need to change the DataTable to strongly typed object before using the DI implementation.

Design, don't Code Yet

 Why - Risk at Development

As a programmer, sometimes I doubt whether I should wasting time to think and design about the application that I will develop or not. As a single programmer-architect, there are some self-defined projects where I usually start by code first or by design first. Logically, they should have produced the same result, thinking that the developer and the architect is the same person. Practically, I'm surprised that the project started with code first is tend to have more risk and more likely to be stopped than the one by design-first.

So, logic does not apply here? Yes it is. The reason is basically that the developer is human. and they will likely get bored because of several reasons:

• The project does not has exact requirement and scope
• The project does not has exact release strategy
• The project is most likely isn't needed by the user

The project does not has exact requirement and scope

Once, I have tried to create a so-called "ideal-best" application. The application should be able to handle many kind of business process. That application will be free of bug, easily extendable and has good architecture foundation. And the application can work as both transaction handling or event high level management reporting tools.

It sounds like a good plan at the beginning, however with such a big regards I need to drop the development because I got bored during developing it. It has no exact scope, no exact plan about what I must develop, what I must validate, how is the process after doing this and that, etc. The scope is growing and growing each day I think about the application, and the development cannot follow the planning growth. You have not target to accomplish, and caused you to loss interest in the development.

The project does not has exact release strategy

 What I mean about the term of release strategy here is a strategy about how to deliver the application. It consist of release date, the audience and the platform target. It may has more details than that such as how to replace the current running application without breaking, or how to not breaking other applications which is dependent to it; but it's regarding what kind of application that want to be delivered.

Having no release date deadline (target) can affect the development scope, since you will think like "I have unlimited time to develop this" or "I can add this and that feature before delivering the application, since the release date isn't being decided". 

Lack of audience target can also affect the scope, because you will try to create an application that can be used by any level of management (transaction level or event advanced-level ad-hoc reporting).

Lack of platform target can demoralize your development. You will be haunted by thoughts such as "will it works well in firefox, chrome, or IE?" or "will it works in other-windows operating system?". Thoughts like that will drag your development, because you will be bugged by how you will check them each time you make a modification. Don't be bugged by it!

The project is most likely isn't needed by the user

Any project needed by the user should has estimated release date. In terms of user, the faster the deliver date, the better. Sometimes you may think that this kind of application/enhancement will not be needed by the user. It can be because you can do manipulation to the database directly. This kind of thought can demoralize the development, since you don't know exactly how your application can give good benefits to the user. Don't develop any kind of application which won't be needed. Or if it will, don't ever think that the workaround (direct manipulation) can be the replacement of the application.

Conclusion

Always design your application first before do code. No matter how skillful programmer you are, the risk of not having the application designed beforehand is high. It can makes your effort go waste, and you got nothing from it, except wondering why this is happening. If you cannot do the design, as someone who is good at it. Asking experts in each field, for example accountant during finance application design or a headmaster during education application design. It can give you clear vision about what kind of application you want to develop, and the functionality.