Year: 2012

There comes a time for every developer when they must work with code written by somebody else. Some times it’s voluntary. Say for instance there is a useful library the developer wants to use instead of writing all the code themselves. Other times, it’s not. Like when a new developer joins a project already in progress. The example in this post is of the former.

I was recently working with a Unity plugin which enables easy development of 2D environments. Given that Unity is a 3D engine having a framework for 2D scenes is useful and speeds development. The team unanimously decided to use an existing plugin instead of building one in-house. We immediately started building the game around this framework. However we did have to pay a small fee.

A couple of days later came a surprise. The developer of the library released a major update. Version 2.0! Given that we had purchased the library less than a week before, we tried contacting the developer to find out if we could get the upgrade for free. We were a little concerned with the response, or lack thereof. We didn’t receive any response at all. Not a yes, not a no, nothing. Not a big deal, we still had version one to use.

Fast forward a few weeks, and then comes an issue. It turns out there was a bug in the library affecting sprites inside a scaled parent. I was able to fix the bug, but only by introducing another issue. Any sprite not in another object moved. I then found out the new version of the plugin fixes the bug among other new features. However, since we had not heard back from the developers it would be a paid upgrade for us.

In the end we bought version 2 of the library only to find out it introduced the same issue my fix did.

Anyway, there is no real lesson to learn from all this. It’s just one of the many issues we dealt with during development.

When I started work on Crowman & Wolfboy there had already been some development complete on the game. A few levels were already built and saving and loading were being coded. However we soon ran into several problems with development.

Documentation seemed really out-of-date with the original engine. Code wasn’t working as the documentation specified it should. Even the examples given didn’t work. It was a serious problem which made progress slow.

Not long after joining we started looking into alternatives. First, we came up with a list of requirements which an alternate need to meet to even be considered. With nearly all the art complete, the new engine needed to support 2D art assets. Nearly all engines are capable of this. A strictly 2D engine is the obvious answer, but 3D engines can be clamped into 2D so we didn’t want to rule them out. We wanted to target both iPhone and Android mobile platforms so solutions specific to one platform were quickly excluded. For example, when we were doing this Cocos2D only supported iOS and would require another separate engine for development on Android. Next, documentation needed to be current. This was the original problem we were trying to get away from.

From this list of requirements we narrowed the possibilities and eventually chose Unity. It is a 3D engine but has several frameworks for building 2D games. It supports exporting to both iOS and Android platforms. And lastly, documentation is excellent. As an added bonus, there is an active community using Unity.

Since switching we haven’t looked back.

In the previous post I describe several forms of documentation and their uses. Hopefully it’s clear that each form is important and serves a distinct purpose. In a typical day, I find myself referencing at least two of these forms. some days I don’t reference any documentation. On days I do, it is most often a function list and forum.

For example, I might start off the day needing to do some complex operation with an object’s rotation in Unity. You can see Unity’s class list with the rest of their scripting documentation. I know an object’s rotation is represented by a quaternion so let’s start there. Now I see that the operation is already implemented as part of the class requiring only one line o code on my part. Later on, when it’s not working the way I expect, I can heard either their forum or Q/A site. Now I can search for other people with the same problem or ask a new question myself. An answer will probably send me back to the class list as a reference.

These are the kinds of connections present between all the forms of documentation. Each one serves a specific purpose and knowing that purpose will help you find information faster.

When I tell non-progammers I’m a software engineer most of them ask about coding languages or mention something about HTML. They have this idea that programming is all code all the time. A lot more goes into programming than just code. Before writing any code an engineer needs to know what capabilities are already provided to him/her. This is known as documentation.

Documentation comes in many forms. You probably already know one. Dictionaries are the most basic forms of documentation. They exist for spoken languages as well as computer languages. They contain words and their definitions. Some even contain grammar information. The dictionaries for computer languages are often called specifications. They contain the reserved words and grammar definition of a language.

Every computer language has a specification. The Java specification is on Oracle’s website. The specification is the most important form of documentation for a language. It defines what can and cannot be written in the language. The specification also defines the syntax of the language. However, as important as a specification is, they are rarely referenced. Most are difficult to read and contain more information than the common programmer is looking for.

The most common form of documentation is a class or function list. This kind of documentation varies from language to language but all have the same basic information. They contain predefined classes, methods, and functions for use in code. PHP has an excellent function list with the ability for people to leave comments. Another excellent example is the Mozilla developer network. These types of documentation are useful because a programmer can use functionality which is already built and tested instead of having to build their own. Most of my bookmarks are to a class list for something. The Unity game engine actually includes a class list as part of its installation making it easier to find documentation while offline.

A third form of documentation is what I call tutorials. They go by many names, tutorial, how to, cookbook, et. al. They contain examples of how to do basic or complex tasks. These are useful when there isn’t a single function to accomplish a task, but you know it is commonly performed. Looking up a task in a tutorial often yields a simple example and information for more complex situations.

The last form of documentation I will cover is the forum. This kind of documentation is a little different from the others. People ask questions and others answer. It requires a community of people capable of answering questions. There are many forums about programming. The most popular now is stack overflow. What makes these work is the community. With so many people willing to answer questions it is likely there is somebody capable of answering one you might have. Over time the forum becomes a reference as more questions receive answers.

There are other forms of documentation like BNF and class diagrams which I may cover later. Until then, know the differences and purposes of each kind of documentation.