Software Development Resources
Create account | Log in | Log in with OpenID | Help

Code documentation

From DocForge

Code documentation is documentation which is specific to the details of the source code used to build an application. Going further than simply reading code, this text can expand on intent, background, and thoughts of the programmer, providing context. Code documentation is most useful to programmers who aren't already familiar with the source code.

Code documentation may be written by every developer on a project as it's being built, by the project lead, or by a technical writer. The most specific and accurate documentation is typically written by the programmers as code is written.

The intended audience for code documentation is typically other software developers who will support the project. Others interested in the document can include project managers, testers, clients, and compliance or certification groups. Technical project managers will want to validate the documentation is thorough and will be useful to others. Testers can use it to help write test cases and to ensure they have full code coverage in their testing. Clients or project stakeholders often require technical documentation to help validate the project is being built correctly and to educate any other groups involved. Compliance groups or certification organizations might require the document as part of their process to certify the software for certain uses.


[edit] Contents

There are a variety of ways to document code. The following topics are often covered.

[edit] Flow of Execution

Staring at source code it's often overwhelming to conceptualize the execution path of the application. Documentation should help explain the basic flow, as well as how changing data and other conditions such as user input will affect the execution of the system. User stories and diagrams will often make this most clear.

A web application's code documentation, for example, might explain how the requested URLs map to specific classes or functions. Especially in large applications, it's important to document where and why execution gets passed around to different servers and segments of code.

[edit] Code Organization

Class structure, file organization, and anything else related to code organization should be explained.

[edit] Dependencies

Any libraries or systems external to the software should be thoroughly documented. This includes 3rd party APIs, software libraries, data sources, and anything else outside the code which is required for the code to function properly and completely.

[edit] Class and Function Definitions

Ideally each module, function, class, interface, method, and property is explained. It should be obvious after reading the description why each segment of code exists. Function and method definitions should include inputs and return values. System exceptions should also be explained.

[edit] APIs

If an application exposes APIs, they must be documented for other developers to properly access the interface. It should also be documented internally so it's clear exactly what will occur when an API is executed.

[edit] Special Cases

Where anything unexpected might occur, confusion arises. For example, if a particular character found in a string has special meaning and could cause a unique path of execution, it should be documented.

[edit] Generated Documentation

There are tools which will turn source code and code comments into standalone documentation:

[edit] Related Documentation

[edit] See Also