What is code documentation?

Code documentation is written text that accompanies computer source code. It is usually written by the programmers who created the program, and it is meant to help other programmers understand how the program works and how to use it. Documentation is important for users of the code, especially if it is complex or challenging to understand. Good code documentation can help developers and other users save time by providing clear and concise information about the code's purpose, function, and operation.

Code documentation can take many forms, including comments within the source code, separate documentation files, and online documentation. The level of detail and format of code documentation varies depending on the audience and purpose. In general, though, code documentation should be clear, concise, and easy to understand. It should provide enough information to help users understand the code, without overwhelming them with unnecessary details.

The benefits of documenting code

There are several reasons why you should document your code. It makes it easier for others to understand what your code does, can help you debug your code if there are errors, and can help you keep track of changes to your code over time.

• Improved readability: Quality documentation serves as a road map, guiding the reader through the complexities of your code. It expedites the learning process for new team members and enhances the readability of your code for everyone, including your future self.
• Streamlined maintenance: Documented code is easier to maintain and upgrade. It’s crucial when you are troubleshooting or when refactoring your code base.
• Enhanced collaboration: In a collaborative environment, documentation ensures everyone is on the same page. It reduces confusion and streamlines development, as any team member can pick up where another left off.
• Reduced dependency: Well-documented code reduces dependency on the original developers. It makes handovers smoother and reduces the risk associated with staff turnover.

By documenting your code, you can make sure that your code is understandable, error-free, and up to date. But despite these benefits, code documentation often gets overlooked. This oversight usually stems from common mistakes that developers make.

Read on: What Is The Most Popular Programming Language In 2022?

What should good code documentation include?

Crafting good code documentation is both a science and an art. It requires a thorough understanding of the codebase and a knack for conveying complex ideas in a clear, concise manner. When done well, documentation serves as an invaluable tool for understanding and navigating the software's inner workings. Here are the key elements that good code documentation should include:

Overview

This is the 30,000-foot view of your software. It should describe what the software does, its scope, and its intended audience. An overview helps newcomers understand the software's purpose and context.

Setup instructions

This includes the necessary steps to get your software up and running. It should contain detailed instructions for installation, system requirements, and any dependencies. This information is critical for anyone trying to work with your software for the first time.

Code structure

This provides a high-level map of the codebase. It should outline the architecture and how different components interact. Understanding the code structure allows developers to know where to look when they need to read or modify code.

Function descriptions

Documentation should provide detailed descriptions of functions, methods, and classes. These descriptions should explain the purpose of each function, its inputs and outputs, and any side effects. This helps developers understand what each part of the code is supposed to do.

API documentation

If your software exposes an API, the documentation should include comprehensive API documentation. This includes details about endpoints, request/response formats, and any applicable error codes.

Design decisions

Explain why certain design decisions were made. This could be due to performance, historical reasons, constraints, or any other factors that influenced the decision. This helps future developers understand why the code is the way it is.

Examples

Including examples can greatly enhance your documentation. This can be as simple as small code snippets demonstrating how to use a function, or as complex as full-blown use-case scenarios. Examples help developers understand how to use your software in a practical context.

Troubleshooting guide

This part includes common issues and their solutions. A troubleshooting guide is an excellent resource when developers encounter problems or bugs.

Change log

A record of all the changes, updates, and fixes that have been made in the codebase. This gives developers a history of the software, which can be useful for debugging and understanding the evolution of the code.

Contact information

Finally, documentation should provide contact information for the team or individual responsible for the code. This is crucial for developers who may have questions or need further clarification.

Remember, good code documentation does not just describe the 'what' of the code; it explains the 'why'. It goes beyond just documenting the code's current state and delves into the reasons and rationale behind the design and implementation choices. This context provides valuable insights for anyone interacting with the software, fostering a better understanding and smoother development process.

What could happen without code documentation?

A notable example of documentation failure is the disastrous 1999 Mars Climate Orbiter mission. The lack of clear documentation led to a mix-up between metric and imperial units, causing the spacecraft to disintegrate in the Martian atmosphere. The incident highlighted the importance of clear, unambiguous, and standardized documentation.

The Y2K bug, or "Millennium Bug," provides another stark example of the potential fallout from inadequate code documentation.

In the early days of computing, to save on expensive memory resources, developers represented the year in date codes with two digits instead of four (i.e., '80' instead of '1980'). This was a reasonable and necessary solution at the time, but as the year 2000 approached, it became apparent that this shorthand would cause widespread problems. Systems would interpret the year '00' as '1900', leading to potential widespread failures in everything from banking systems to power grids.

Resolving the Y2K bug became a massive, global effort that cost an estimated $300 billion. The challenge was not only in finding and correcting the two-digit year codes but also understanding these often old, poorly documented systems. Code written in the '60s and '70s did not always have the extensive documentation we expect today, and many original programmers were no longer available (or even alive) to explain their code.

For example, imagine being tasked with auditing and correcting a piece of banking software written in COBOL in the '70s. Without proper documentation, you would first need to understand the system's purpose and functionality and decipher the logic behind decades-old code, even before starting to correct the Y2K issue.

This example underscores the importance of thorough, up-to-date code documentation. Good documentation ensures that your code remains understandable and maintainable, regardless of how much time has passed or how many of the original developers are still around. It future-proofs your code, facilitating updates, modifications, and bug fixes, and helps prevent potential crises—like the Y2K bug—from happening.

To prevent such mishaps and to make the most of your code documentation, here are some best practices to consider.

Best practices for code documentation

1. Set documentation standards: Consistency is crucial in code documentation. Set standards in terms of language, format, and the extent of details to be included. Consider using documentation generators to enforce consistency.
2. Focus on why, not what: Good documentation should explain the 'why' behind the code rather than just the 'what'. Explain the purpose, the rationale for your choices, and any non-obvious elements of the code.
3. Use inline comments wisely: Inline comments are useful but should not state the obvious. They should be reserved for complex logic or areas where the code cannot express itself clearly.
4. Keep it updated: As mentioned earlier, outdated documentation can do more harm than good. Make it a habit to update documentation along with code changes.
5. Review documentation: Just like code, documentation should also be reviewed. It is an integral part of the codebase and should be treated as such.
6. Automate where possible: Automated tools can generate parts of your documentation, such as API references, based on your code.

Common documentation mistakes

There are many common documentation mistakes that can occur when writing documentation for software projects. Three of the most common mistakes include:

• Under-documentation
• Over-documentation
• Relying on tests to document code

Under-documentation

Often, developers tend to believe their code is 'self-explanatory'. They overlook the need for documentation, leading to a lack of clarity for others (or even themselves at a later date). Code under-documentation generally refers to any form of documentation that makes it difficult or impossible for developers to understand and work with code. This can include out-of-date or incorrect information, and insufficient detail.

Bad code documentation can have a number of negative consequences. It can make code more difficult to maintain and update, which can lead to bugs and security vulnerabilities. It can also make it harder for new developers to join a project, as they may struggle to understand the codebase. In extreme cases, bad code documentation can even make it impossible to continue developing a project, as the original developers may be the only ones who understand it.

Over-documentation

At the other end of the spectrum, excessive documentation can also be problematic. It can lead to unnecessary verbosity and create confusion, especially if it becomes outdated. The extra documentation can also be time-consuming and difficult to create. For this reason, many programmers choose to only document the parts of their programs that they think are most likely to be useful to other programmers.

In addition, over-documented code is often outdated soon after it is written, since programs tend to change over time. For these reasons, it is important to carefully consider whether more documentation is necessary before spending the time to create it.

Outdated documentation

Documentation needs to evolve with code. Neglecting to update documentation after code modifications is a common error, which leads to inaccuracies and potential misunderstandings.

Lack of clarity

Using unclear language, jargon, or vague descriptions can make documentation difficult to understand, defeating its very purpose.

Can I automate code documentation?

Automation has been a significant driving force in enhancing efficiency and productivity in various areas of software development, and code documentation is no exception. Yes, you can automate certain aspects of code documentation. This automation often comes in the form of documentation generators.

Documentation generators are tools that create documentation directly from your source code. They work by extracting comments and symbolic information from your code and formatting them into readable and navigable documentation. Some popular documentation generators include Javadoc for Java, Doxygen for C++, and JSDoc for JavaScript.

These tools are particularly good at creating API documentation, providing information about classes, methods, functions, parameters, and return types. The outcome is typically structured, consistent, and easy to navigate.

However, while these tools can provide a solid structure and take care of much of the grunt work, they do not eliminate the need for manual documentation. They generate documentation based on what's in the code, so they're only as good as the comments they're processing.

Moreover, automated tools might not capture the high-level design decisions, the reasons behind certain implementations, or the explanations of complex algorithms. These nuances are incredibly important for a comprehensive understanding of your codebase, and they require a human touch.

Therefore, it's best to view automated documentation as a supplement to, rather than a replacement for, manual documentation. A combined approach ensures your documentation is both thorough and efficient. Developers should still focus on writing clear, concise comments and providing details that cannot be derived directly from the code.

Remember, the primary purpose of documentation is to facilitate understanding and maintainability. Whichever method or tool best helps you achieve that, be it manual documentation, automated generation, or a combination of the two, is the right one for your project.

5 tools for code documentation

Tools play an important role in code documentation. They can help you automatically generate documentation, and they can also help you format and manage your code documentation. Let's take a look at some of the most popular tools for code documentation and how they can help you.

Doxygen

Doxygen is a free and open source documentation generator for C++, C, Java, Objective-C, Python, PHP, SQL and other programming languages. It can generate an online class browser (in HTML) and/or an offline reference manual (in LaTeX or RTF) from a set of documented source files. There is also support for generating output in PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation generated by Doxygen can be used to generate both internal and external documentation.

Javadoc

Javadoc is a documentation generator created by Sun Microsystems for the Java programming language. Javadoc generates HTML pages of API documentation from Java source files. The HTML pages can then be viewed with a web browser. Javadoc also provides an embedded tool called javadocsearch that enables one to search all the documentation from a web browser.

Javadoc comment tags start with /** and end with */. Anything between these two tags is part of the Javadoc comment. A typical Javadoc comment contains two parts: a description and one or more tags. The description can be plain text or HTML.

Natural Docs

Natural Docs is an open-source documentation generator for multiple programming languages. Natural Docs generates HTML, LaTeX, RTF, and XML documentation from comments in over 25 programming languages. It supports both single-file and multi-file documentation projects, with the ability to cross-reference between them.

phpDocumentor

phpDocumentor is a documentation generator for PHP, written in PHP. phpDocumentor can be used from the command line or integrated directly into an IDE such as PHPStorm, NetBeans or Eclipse.

phpDocumentor generates documentation in HTML, PDF and CHM format from PHP source code files. The documentation generated by phpDocumentor includes class diagrams, source code cross-references and tutorials.

pydoc

pydoc is a tool that automatically generates documentation for Python modules. pydoc can be used to generate documentation in HTML, PDF, PostScript or text formats from Python source files.

pydoc can also be used to generate documentation for Python scripts and packages. To use pydoc, simply type "pydoc" followed by the name of the Python module or package you want to document. For example, to generate documentation for the "urllib" module, you would type: pydoc urllib

At Rare Crew, we always keep best practices in mind, which is why we believe proper code documentation is so important. Keep it clean, keep it concise, and keep it easy to understand, and you’re set.

Are you passionate about coding and want to take it to the next level? Reach out and send your CV to jobs@rarecrew.com, or get in touch with our HR Manager Zuzana Matuskova for any questions.