Home » Articles

Software SOFT/INTERNAL Documentation Guide

By: IncludeHelp, on 20 JAN 2017

If you are writing code for a company or for an open source community, without documentation your source code is nothing. Nobody will find it useful, even after sometime you will also get confused why you wrote such code segment.

People need to understand, why the code written by you is useful for them? They will not use your code, if they don’t know what your project is and how to use it?

If you want people to help out, document your code properly. Soft/Internal documentation helps to others to understand the source code better.

Benefits or the Soft/Internal Documentation

Documentation may take time but it is useful to you and others, the benefits are:

1. If your code/project is documented consistently during the project development phase, the resulting product's quality will be higher than undocumented project.
2. A documented project is easy to maintain - the other programmers can easily understand the flow of the source code, even the original programmers can use the documentation to remind their logics and source code’s flow.
3. A documented project helps you to track the modifications easily.

How, when and where you should use comments / documentation?

I'm writing few points to explain the exact places in the source code along with other supportive files which are also the important factors about Soft/Internal Documentation.

1) Describe the purpose of source file

A comment block should be placed at the starting of each source file; the file may contain File Name, Purpose, and Team Member’s Name (if there is more than one programmer). This comment will help to understand purpose and functionalities of the particular source file.

2) Describe the user define functions/methods

Each User Define method should be documented within the source code, the comment should include following information:

• Method/Function Name: Method/Function name with return type and all parameters should be there.
• Method Description: Method Description should contain detailed explanation about the Method’s functionalities, purpose. Why and when the Method is going to be use?
• List of all parameters: Purpose of all parameters with possible values should be documented, so that the functionalities of the Method can be understandable easily. If there is no parameter, you should mention as void.
• Return Type: Method's return type and return flow should be documented.
• Author Name: Code writer/ Author/ Programmer’s Name should be there.
• Date: Method creation date.

3) Describe the logic

The logic that you are going to use, must be documented i.e. comments should be placed within the source code. These comments should include following information:

• Each variable, constant, macro etc should be briefly described next to its declaration (purpose of declaration, default value etc).
• Each condition or complex code segment should be documented with its purpose (comments can be placed just ahead of the statement).

4) Describe the modifications

If you are modifying the any function, which has written by other programmers following information should be placed within the comment:

• Modification Date: The date on which you have modified/optimized the code.
• Modification Purpose: The purpose of modifications should be described.
• Author's Name: Who is going to be modified the code.
• Remarks: If there is other information that you want to provide, just place the information under the remarks section.

5) Project history file (Change log)

There should be a file within the project to write/update the modifications, this file should contain the following information with each change note:

• Source file name in which you have made the modifications.
• Optimized/Modified method name.
• List of all modifications and their purpose.
• Date wise entry of the modification and implemented features.
• Author's name.
• Maintain the version revision history.

6) Readme file

If required, put a "Readme" file within the project, where you can write instructions about source file’s usages, library configuration, makefile instructions or other compiling, installing instructions.

Soft/Internal documentation is an important part of project development phase, it is as important as the source code.