Developing By Me

Project Development and Design

Documentation

There are many different articles about how to program different concepts. However many times the simple concepts are lost. One area that is often overlooked is the need for documentation and how it should be applied within the application. There are different types of documentation that need to be addressed when designing any application and games require more detailed documentation in many respects since they tend to be more complicated then business software. Some common standalone documents are the System Requirements Specification [SRS], User Manual, Design Specification Document [DSD] and others which are all important to keep the software consistent. Each of these standalone documents could be a whole article on its own. However, it is more important to document the code properly. Documentation within the code is more valuable than any other documentation; this is because future developers may not have accurate design documents but they will have the current version of the application available to look at.

Documentation in an application is done through commenting the code. Since most languages are based on C/C++ methodologies they will be addressed. If the developer reading this is working with a different language pattern similar constructs are available within the language. So what kinds of comments are available? There are two types of comments single line and multiline. Each has a place within the software but being able to tell the difference is important. Single line comments start with // which will mark everything until the end of the line as a comment which the compiler will ignore. The multiline commends are in side of /* … */ and can be placed within a single line of code or spanning unlimited number of lines.

Now that the notation is defined where are they used within the code? The simplest way to explain is to show them. The following class could come from any C language some languages may vary slightly however for the most part they are roughly the same.

/******************************
* @File: test
* @Author: Stanley
* @Description: this is an example file
******************************/
class SomeClass {
    // Members
    public int x;
    protected int y;
    private int z; // used to modify u

    /**
     * default constructor class
     */
    function SomeClass() {
        // TODO: some magic
    }

    /**
     * Function modifies the value of u
     * and returns the new value
     * @param int u
     * @return int someint
     */
    function int SomeFunction(int u) {
        /* TODO: some magic
        Then do some more magic
        Followed by even more */
        return someint;
    }
}

The above code uses both single line and multiline comments. The class is very generic and has no real functionality however the comments tell us what can be expected inside the class and functions. As explained some of the comment styles might be different in languages such as PHP, Java, C# or others however the general idea is the same. Comments on a class should always explain the class in brief. It should always contain the file, author, and description, however, some systems might also recommend or require language, dependencies, or other information.

The comments within the class are slightly different. It is important to denote local constants, public, protected and private members. These should be commented with a single line quote as the list could be quite long. If there are a lot of members and the names are not descriptive enough then a comment can be tagged on to the end to explain the usage a bit more. Functions should always have comments defined. The comments will always define the inputs and outputs with a description. These comments are used by the development environment to hint what the function will do and what values the developer can expect to send as inputs and receive as an output if it exists.

Finally the comments within the functions are often single line however can also be multiline depending on the need. Single line comments should be used to break up the code and explain what is going on. This is typical in large complicated functions that do not make sense to break down into smaller functions. Multiline should be avoided in a function because if there is a requirement to have more than a 10 word explanation of a code block it most likely should be in a dedicated function.

What to do to minimize in code comments? This is simple actually. In the above example single letter variables such as `x`, `y`, and `z` are used. This style variable does not explain what the values are to be used for or what data type is required. By adopting a naming convention that is self-documenting the need for inline comments are not required. The variables could be `iScreenX`, `iAxisY` or `iOffsetZ`. By using the more descriptive variables the future developer knows what data type the variable is as denoted by the first character. It is also known what the value is used for such as screen, axis or offset. And finally it is known which aspect is being addressed. By using this type of naming convention the next developer will not need a lot of documentation to understand what each variable is for only to define the logic as required. The same methodology can be used to name classes or functions.

Different types of documentation are recommended in specific areas of development. It is always best practice to have well defined classes, members and functions. It is also important to have a document such as an SRS which defines the project as a whole and how the classes will relate to each other. Between the different documentation types all aspects of the application are explained well enough for any developer to read the project and know what is required or intended by the code that has been developed. It is not only useful for other developers but for a single developer on a project since any application can take weeks or years to fully develop. Because of the time frame involved with the development cycle documentation allows the developer to track down a bug within the code or the area that needs to be upgraded at a later time. The comments are there to let the reader know what is going on within that section of code and allow them to understand what is going on without having to read every line to understand what is being done.

Related pages

  1. OOP Design Basics
  2. Programming Languages
powered by Related Pages WP plugin

%d bloggers like this: