All software applications receive some form of initial planning as to what their goals are, but quite often the planning occurs in the mind of the developer. A great approach to planning is the creation of an actual software development plan that addresses many high level design issues, as well as technical issues like coding standards and architecture.
A software development plan is an action plan for developing the application. It describes how the work will be done in terms of design, implementation, documentation, and testing.
Software planning is an iterative process, and as unexpected problems arise, change requests will occur that require plan revisions. A good software development plan anticipates that changes may occur, and the plan should be able to accommodate them appropriately.
The software development plan should be kept up to date, typically through regular team meetings. The plan should be modified accordingly for all changes, progress, and problems. Doing so will ensure that the maximum benefit from the planning effort is gained.
Also known as design goals, this section of the software development plan ultimately asks the question, “What is the tool going to do?”
Briefly describe what the tool will do and ultimately how it will either improve workflow productivity or affect the content creation pipeline. Outline the current problems existing without the tool, and how the introduction of the tool will attempt to solve them.
Describe whether or not the tool will be used for a single purpose throw-away, or whether it will be applicable for multiple purposes or projects.
Also list the people who will use the tool. As a simple example: “The technical artists will build programmable shaders using the Visual Shader Designer plug-in from within 3D Studio Max, and export a binary file that follows the specifications of our proprietary VSD (.vsd) format.”
The Vision section of the software development plan could be thought of as an overview and summary of the other sections that follow.
Every software application has stakeholders who will either gain or lose from the success or failure of a tool, and they ultimately shape the design of the tool to meet their needs. After all, the stakeholders for a tool are typically the people who will actually be using it to produce game content or enhance workflow.
The software development plan should define who the stakeholders are, and how they will be directly affected by the tool. The easiest way to determine who your stakeholders are is to think of everyone who will be affected by your work, whether the stakeholders are internal or external to the company. The majority of tools developed for internal use are catered to the needs of artists or technical designers, who don’t always possess strong technical aptitude.
One of the biggest problems with software development planning is gathering user requirements that do not solve the problems of the stakeholders. It is very important that you ask the right questions of your stakeholders, especially if they do not have a technical background. A lot of design and development time is wasted because of incorrect user requirements. Getting them right from the start will help alleviate this problem.
After the stakeholders have been defined, the last step is to sort them by priority and influence. A common approach is to take note of the influence, interest, goals, and objections to your tool. Prioritize your stakeholders as high or low interest, and as high or low influence. It is important to remember that the stakeholders do not always agree with each other, which presents problems with both communication and requirements gathering.
The issue of reusability is important in any software project, but is very important when developing tools. If a tool is a throw-away, not meant to be reusable, then only the minimum amount of time to implement the basic functionality should be spent on it. A common problem is when a tool is not meant to be reused in the foreseeable future, but has the potential for reuse. In this situation, it is advisable to build the tool with future maintainability in mind. If the code is just slapped together to meet deadlines or save money, all those benefits will be for naught when a considerable amount of time must be spent refactoring the tool for a later project when it should have been designed that way from the start.
Designing with reusability in mind, and the level of abstraction or agnostic design to consider, is definitely a judgment call, especially if the stakeholders are putting pressure or constraints on you to prevent you from doing so. Maintainability even comes in the shape of following coding guidelines, commenting any complex constructs, and never using hard-coded values or “magic numbers.”
The golden rule is, build reusable code if the functionality of the tool would be useful in a future project, and if it is feasible to spend a little extra development time building it. You will gain in the long run when the time comes to build a tool that solves a problem encountered before.
This section outlines the architecture of the tool or toolset. For a simple tool, this section will be quite brief, just outlining whether the application is console-, Windows-, or web-based, and other technical issues related to the application.
However, more detail must be discussed with complex tools or toolsets, tools utilizing a wide range of technologies, or complex component dependencies. Outlining the architecture is especially important when thinking about reusable software component design, and how to write software with future reusability in mind.
This section addresses what the tool is supposed to do. As mentioned earlier, stakeholders are the people using the tool, so the requirements are generally centered on their goals and expectations. I cannot stress the importance of this section enough. The majority of tools that fail to deliver are because of malpractice with gathering user requirements. Developers often over-complicate interfaces or build complex functionality when all the stakeholders wanted was a throw-away utility to perform a simple process.
If user requirements are gathered correctly from the start, you will save both yourself and your stakeholders a lot of grief and expense. The old saying, “Time is money,” describes this problem best. When you are on a tight schedule to produce tools that are required to build the content for a game or improve workflow to meet deadlines, time cannot be wasted on building tools that are of no or limited use to the end user.
Every software application goes through a design phase to some extent, and it is important that you standardize how the design of the tool is expressed or modeled. A common method is through the use of the Unified Modeling Language, or UML for short. UML is definitely beyond the scope of this book, but I personally use it and advise that you at least read up on it if you are not currently using another modeling language.
I will admit that UML has a time and a place in regards to software design. Some tools are so simple or unimportant in the scheme of things that it would be a waste of time to utilize UML. A modeling language serves as a way to visualize how all the components of your tool or toolset fit together at a high level, and also aids with future maintainability if the code itself is not self-explanatory.
However you design the functionality and communication of your tools or components, be sure to document your standards in this section and follow them.
A tool or software application in general cannot be considered great strictly on functionality and performance alone. Since the importance of reusability should be quite clear by now, it is apparent that the source code for the application must be easy to read, understand, and maintain for future versions of the software. It is a common fact that every developer has a unique style to his code, which is perfectly acceptable for personal projects but unacceptable for commercial software. All developers should follow a common style so that no matter who wrote the code, it always looks like a single person programmed the entire application.
A common practice to outline how all code should be formatted is to release a coding standards document to the developers. They are to abide by the rules and best practices set forth in the document to promote the creation of code that is easy to read and maintain. Looking through code that you did not write is much easier when everything follows the same style and is neatly commented, with explanations for all the complicated constructs present in the code. Using coding standards will increase both productivity and efficiency through a consistent style, delivering the end product at a lower cost. In addition, coding standards reduce the risk of integration with other components developed by other companies, groups, or team members.
The usage of design patterns and how modules are coupled can also be described in the coding standards document. Some design patterns are frowned upon because they typically promote tightly coupled design, making the code harder to unit test among other things. This document can be used to define acceptable design patterns to use, and which ones to use only if necessary.
In addition to documented standards, Microsoft has released a great tool to help with the actual enforcement of coding and development standards. Microsoft has published design guidelines for all .NET applications to follow, and FxCop is a tool that uses reflection, MSIL parsing, and call-graph analysis to inspect assemblies for over 200 violations of the design guidelines. Custom rules can also be created specifically to your own guidelines and used within FxCop. Some of the default rules check for conformance issues with library design, localization, naming conventions, performance, and security.
Note
FxCop can be downloaded at http://www.gotdotnet.com/team/fxcop/.
As discussed numerous times throughout this book, the importance of developing tools that promote maintainability and reusability cannot be stressed enough. Documentation is a deliverable that will assist developers working on future modification or reuse of a tool or component. Documentation can be created for either source code or usability, and requires standardization just like source code.
Source code documentation is primarily aimed at developers who want to understand the functionality of a given component without the need to look at the source code to understand what is going on. The .NET framework has a standardized way to document source code, expressed as XML. Chapter 11, “Code Documentation with NDoc and XML,” outlines the way Microsoft wants developers to document source code to remain consistent with the core framework. When a .NET assembly is compiled, an option exists to export all the XML-based source code comments to a file that can be referenced by a number of documentation generators.
An excellent tool exists that can take a .NET assembly and the associated XML comments file and build documentation. The tool is called NDoc, and it supports pluggable exporters including the MSDN-style HTML Help (.chm), the Visual Studio .NET format (HTML Help 2), and the MSDN-online style Web pages. This tool is very popular within the .NET community and is the most commonly used documentation generator for .NET.
Note
NDoc can be downloaded at http://ndoc.sourceforge.net/.
Usability documentation comes in the form of training manuals or reference materials that instruct users how to use the tool, or how to solve real-world problems with the tool. This type of documentation is high level and does not discuss the inner workings of the software; it merely shows users how to use the tool.
The Documentation section should discuss the documentation standards to use, such as NDoc or a specific template to use in Microsoft Word. Also describe how function descriptions, properties, property accessors, and classes are worded.
Testing is a very important part of any software development project, and the intent of this section is to standardize how testing takes place within the project. There are different types of testing that can be performed, such as unit, automated, functionality, and performance. Each type of test should be documented and should list all the proper procedures and guidelines to follow, along with all the necessary software to use to perform the testing, such as Rational Robot, ANTS Profiler, NUnit, and csUnit.
Standards must also be in place for how issues are handled when they appear in tests. This section should outline where issues and defects are tracked and registered, and how to handle them. Certain defects and issues are more important than others, and should generally be handled in terms of priority and influence on the stability and functionality of the tool. Be sure to describe how to prioritize certain issues and handle them accordingly. Also specify where defects and issues are stored, such as Rational ClearQuest or TestTrack Pro, for example.
The Life Cycle section of the software development plan outlines how the software will be developed, and describes the software development methodology that will be used: Rational Unified Process (RUP), SCRUM, and the Waterfall approach, for example.
This section could potentially list the milestones and deadlines for the project if they are known, but typically the specific project dates reside in a project schedule, a topic outside the scope of this book.
There is a detailed overview of the software development life cycle (SDLC) in Chapter 5, “Development Phases of a Tool.”
The approach covered in Chapter 5 is the Waterfall approach, though there are many different methodologies that are in use in the industry.
The Development Environment section of the software development plan outlines the development environment and resources necessary to design and build the tool.
First, describe the hardware specifications of the development computer(s). Also describe what operating system(s) will be installed on the computer(s). If multiple operating systems will be installed for testing, describe whether or not they will all be accessed using a dual boot loader or a virtual operating system manager. Also specify what networking requirements are needed, such as Internet access or permission to access specific local domains.
Second, you should outline the software that will be needed, such as compilers, debuggers, IDEs, frameworks, and libraries.
Last, discuss workflow processes that will be used, such as which document control and versioning system(s) will be used, as well as how the project will be backed up and at what time intervals.
Every software application, in general, requires a certain level of testing. Tools that enhance workflow productivity or produce game content require an extra level of consideration for quality assurance, as a faulty tool can harm productivity or produce corrupt game content that requires time to fix or redo.
It is important to outline an environment suitable for testing, and it is recommended that this environment not be shared with the development environment. Using a unique staging environment allows testers and developers to locate conflicts with missing dependencies, hard coded values, or system variables, and other issues that could lead to deployment problems. It is also advisable to periodically rebuild your test environment to make sure that other issues do not slip through before staging deployment.
The staging environment should typically mimic the production environment, and only have the absolute necessary software and libraries installed. Never install development software in the staging environment or do any modifications there. Fully uninstall your application after testing, modify the source in the development environment, and redeploy your application to the staging environment. This may seem like a trivial and inefficient process, but doing so will save you a lot of headaches during production deployment.
The staging environment should also contain a relatively diverse range of hardware and software configurations that could potentially be used in the production environment. If the application requires 3D acceleration, be sure to test a variety of graphics cards, especially older cards that do not support the features your application requires, like a programmable pipeline, for example. Be sure to test configurations that are guaranteed to fail, and observe that all fatal errors are handled gracefully.
The Production Environment section of the software development plan outlines and describes the environment in which the final application will run. Some tools will only be run on one type of configuration or computer, which often is the case when the tool is developed for internal use. With a tool developed for external use, this environment is any computer or configuration that is managed by the stakeholders of the tool. The production environment is fairly similar to the staging environment. All the deployment issues should be resolved when the application reaches this environment, allowing for a clean install with no missing dependencies or settings.
Building a software development plan with standards plays an important role in development. A comprehensive plan is typically a waste for small tools, though even a brief description in each section is generally sufficient enough. Keep in mind that if you have standards that are applicable to other projects, if not all of them, the extra time you spend writing a comprehensive section for a small tool will be justified when you reuse those same standards in other tools that are of a much larger scale.
Why not wait to write a detailed standard until it is needed for a larger project? You can definitely do this if you want, but if you define the standards immediately, you can build all of your tools to follow your specifications, promoting ease of maintainability across all your projects.
On much larger projects, a thorough development plan and development standards are basically a requirement, especially when working with multiple developers, each with his own coding and documentation style. Remember that consistency is extremely important, and the best way to achieve consistency is through defined standards.