Prototyping and Code Quality

Prototyping is a popular method for getting a feel for the core features of a given application. It is often used as the first step when your company is looking into a new prospect with a lot of uncertainty. The method relies on short iterations to quickly verify whether a set of new functionality is worth investing in.

In this article I focus on how code quality is related to a project developed using prototyping. I will first go through some of the main stages of such a project followed by some pit falls that you should avoid when moving into actual production.

The prototyping phase

Let’s imagine you are in the following situation. You have a great idea for an application or a game and the competence to make it. The first stage of development is going to be research. You will start looking at competing products in order to see what their shortcomings are and whether you should tackle them in your product.

After you have figured out a suitable set of features and nailed the higher level vision of the product you can start prototyping. In prototyping you build one or more smaller applications in order to test the core features that were found to be central to your product.  This stage of development consists of a number of very small iterations where your primary goal is to implement features so that decision makers can try them out to see whether they work or not.

At this point in development it's important not to focus too much on code quality and documentation. Code written for the prototype should be clean enough for you and other developers working on the prototype to be able to develop features with. Supporting a too high quality level slows down your work and does not add much value to the prototype. This is because, as will be discussed later in this article, prototype code is meant to be "thrown away".

To minimize the amount of work being thrown away, the code should be as light as possible. This means using architectures and frameworks that allow flexibility and don't lock you in on certain ways of working. For instance, if you are developing a game that is going to have an online component but the feature set you are currently prototyping does not require online play, you can safely omit the online part all together.

Moving on to quality code

Once you are ready to move into production with the software, I would recommend using the prototype as a reference more than an actual initial implementation. This is because you now have a rather detailed map of the path in front of you when it comes to implementing the prototype features in the actual product and keeping the prototype intact helps you navigate in the future.

Reimplementing the features in the prototype has multiple benefits:

Architecture

When starting to develop the actual application you should first do some research on the platform and frameworks you have chosen to use and make sure your choices are still valid. You might want to draw a couple of images and write a few lines of design documentation that will lay out the base of your application architecture. Architecture documentation is important but you should not overdo it. I wrote earlier about documentation in general and I think it’s important to keep it on a sensible level. Architecture documentation, however, is the most important kind of documentation as it gives you the frames within which to work. It’s also very difficult to describe architecture in code commenting or code itself. This is because architecture defines aspects like naming conventions and component interoperability that are more global in nature.

The software architecture will follow you throughout the project. It forms the basis of the whole application, it’s form, if you will. This is why it should be clean and clearly communicated and all developers in the project should follow those same guidelines. Good architecture actually forms the basis of good quality code, which is why it deserves its own section in this article. If all code follows the same form it’s easier for everyone to understand the details when the form is already understood. This also leads to less buggy code as developers know instinctively what is happening and where, as you speak the same language with familiar words.

Once you have an idea of the software architecture you can start working on the actual code. Sometimes you will have to make modifications to the architecture during development. It’s not as frequent as making modifications to individual features due to requirements changes but it still happens. These changes should be clearly justified either by significantly improved code quality, performance or just making a crucial feature possible. Changes to architecture should not be made lightly. It’s like changing the constitution of the application, and constant changes will lead to chaos. You should also always modify the whole application to meet the new architecture definition. It’s not a good idea to have remnants of the old world lying around.

When developing the architecture of the application you should also consult people who are going to be developing the application with you. They might have ideas about the high-level implementation of the software. It’s much cheaper to take those ideas into account at this stage of development instead of incorporating them at a later point in time through architecture changes.

Practical tips

Keeping up code quality is a constant process that requires input from every single member of the team. This is why the whole team has to stand by the common guidelines. No single person should dictate developing the software architecture. It’s important to get feedback from all developers as they will spend all their coding hours using it. Minimizing aggravation minimizes the potential of bugs and makes you want to do a better job overall.

I would also recommend leaving the codebase in a better state than you found it in. This will eventually improve the quality and will not require anyone to use a couple of days to get things in order.

Syntax auto-formatting and refactoring in programming tools have been steadily improving making it easier to maintain common coding conventions. They might not be the holy grail and often do little in the form of naming conventions, though. You should always try and use the same terms everywhere in the code with method and property names being formed in the same manner. It might make sense to try and keep an appendix on used terms but I personally would recommend just getting to know the code base and getting a feeling of the different words being used and then just trying to use them in your own code. Although, conventions like always using the word “Is" in front boolean typed properties should be documented in the naming conventions part of the architecture documentation.

Peer review is also a good way of spotting potential issues in code. If done right, you will get valuable feedback on your code. Peer review also has the added benefit of sharing information about the code base. Features implemented by you will be seen by your peers and wise versa. Having someone review your code will show you how understandable the code actually is. It also pushes you to write code you can feel proud of.

In addition to peer review I personally recommend going through your code changes just before pressing the commit button. You should perform a self review, if you will. This way you might recall situations where you thought you would like to do something but had moved on forgetting to write down what it actually was. You also have time to check whether the code is legible, remove debugging code and add commenting if required.

Perhaps the most important tip I can give you is that you should always take code quality seriously. It makes sense from a business point of view but it also helps you as a developer to make your days that much easier and less frustrating!

Summary

Prototyping allows you to figure out what might work and what doesn't. You should not overdo code quality in this phase as prototype code should be light and quick to write. The application prototype should also be used more as a reference than an actual basis to develop the final product on.

Good quality code, especially in the final product, can sometimes mean the difference between success and failure. Code that is written with predefined conventions and following structures that everyone agrees on makes it easier for new people to get into working with the system while also minimizing misunderstandings and thus those pesky bugs.

The most important part of code quality is a good and clean architecture. This includes anything from component interactions to coding conventions. It forms the basis of communication between teammates and makes code much more readable.

You might also want to read my article "What Documentation?" for more on my thoughts on documenting.