What is code documentation?

Code documentation acts as a map for those who interact with a codebase, helping them navigate what each piece of code does, how it works, how to use it and how all the code pieces fit together. Documenting code helps development teams better maintain source code while also guiding other stakeholders who might need to understand and work with code, such as cybersecurity analysts, data scientists, DevOps engineers, product and project managers, QA engineers and technical writers.

Documentation as code or “docs as code” treats documentation like software code. This approach manages documentation using the same tools as source code, including version control systems to review and track changes, automated testing to identify formatting and style issues, and continuous integration/continuous delivery (CI/CD) for updating and deploying documentation.

While code documentation encompasses the wider practice of documenting code, docs as code is a specific strategy and a more technical approach to writing documentation.

The structure of code documentation will depend on who the audience is and how it will be used. Here are some common types of documentation:

• Low-level documentation
  
  
• High-level documentation
  
  
• Internal documentation
  
  
• External documentation

Low-level documentation typically refers to inline comments within code. As one of the most basic methods of writing documentation, these annotations explain particular lines or blocks of code.

Documentation strings or docstrings are another low-level documentation technique. They appear before a class, function, method or module definition. Docstrings have a structured format declaring purpose, examples of usage, functionality, parameters and return values.

Inline comments are better suited for specifying logic when it can’t be gleaned from examining the code itself or for code based on more complex algorithms. Meanwhile, docstrings can be extracted for application programming interface (API) documentation and provide contextual help within integrated development environments (IDEs).

Unlike low-level documentation that describes portions of code as individual entities, high-level documentation includes details about their role in the broader architectural workflow. This type of software documentation encompasses flowcharts and Unified Modeling Language (UML) diagrams illustrating code architecture, design documents outlining business logic and how the code aligns with product requirements, and specifications of the structure of codebases or code repositories.

This technical documentation is for internal use within an enterprise. Examples include coding conventions and standards and process documents for how teams build software. Guides for setting up development environments also fall under internal documentation.

This user-facing documentation is geared toward developers and other users outside of an enterprise. For instance, API documentation lays out the available classes, functions, methods and modules of a software project’s public APIs. External documentation can also consist of configuration files, integration notes and a README file.

The README file is written in markdown, a lightweight markup language for formatting plain text. It contains information about project features, dependencies, installation instructions, command line interface (CLI) commands and options for getting help and support. Open-source projects also add licensing details and contributor guidelines for submitting pull requests to merge bug fixes or code changes into the main branch of the code repository.

Writing code in a clean and clear way can be its own form of documentation. However, good documentation remains essential and offers these benefits:

• Enhances collaboration

• Improves maintainability

• Speeds up software development

• Streamlines onboarding

Well-documented code promotes better collaboration and communication within development teams. Members can harness code documentation as a shared language for conducting code reviews, discussing code changes and making decisions as a team.

Documentation facilitates code refactoring, maintenance and performance optimization. During debugging, developers can use code documentation as a reference point to find coding errors and pinpoint their root cause.

Good documentation paves the way for swift development, saving time on figuring out code functionality and redirecting focus to applying the appropriate code updates instead. It also helps track changes, making sure teams can keep pace with a frequently evolving codebase.

Code documentation aids new team members in learning the inner workings of a codebase. They can familiarize themselves faster with the design and structure of the code, allowing them to quickly contribute to the project.

Code and documentation work hand in hand, so they must also evolve together. And some guidelines for writing code equally apply to writing documentation. Here are tips that can help:

• Establish code documentation standards

• Integrate documentation with coding

• Clarity and conciseness are key

• Document coding decisions 

• Keep it updated

Like coding conventions, standards must also be followed for code documentation. These standards include consistent formatting, such as indentation, line breaks and spacing for low-level documentation. Meanwhile, templates and code documentation tools can help with style and structure for API documentation and other high-level and external documentation.

This might involve adding docstrings upon completing a function or inserting inline comments while implementing intricate algorithms or logic. Writing documentation while programming can help developers articulate their thought process and decisions, making sure crucial details don’t get lost along the way. It might take some extra time at the start but can become a natural part of the coding process and can fast-track debugging, optimizing and refactoring in the future.

Overdocumentation can hinder code readability. Developers must prioritize writing clean and clear code, then add the necessary documentation that neatly fits alongside that code.

When it comes to conciseness, finding the right balance is vital. For instance, short and simple code fragments might need no documentation at all. On the other hand, more sophisticated algorithms require documentation that explain the underlying logic in a way developers with varying levels of experience can understand.

This includes design, architecture, logic and algorithmic choices. Documenting these coding decisions, be it through a high-level internal document or a shared knowledge base, offers context for any changes to be made in the future.

Development teams must conduct periodic reviews and updates of their code documentation to make sure it’s accurate, complete and relevant, reflecting the current state of the software. Incorporating documentation into the code review process can help with regular updates.

Most IDEs have extensions or plugins for generating code documentation, but other frameworks and tools can also assist with automating the process. Here are some common documentation generators:

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen supports multiple programming languages, such as C, C++, Java, PHP and Python. It allows for markdown rendering and can produce documentation in HTML, PDF and XML formats. Doxygen can be customized through a configuration file and provides the ability to generate diagrams depicting visual hierarchies and correlations between classes and functions.

GitBook offers a user interface for writing and publishing documentation as a website, which can make it more efficient to create both internal and external documentation. The platform also features synchronization with GitHub or GitLab repositories.

The Javadoc tool parses documentation comments within Java source code to generate API documentation in HTML format. It can document classes, constructors, fields, interfaces and methods.

Similar to Javadoc, JSDoc generates API documentation for JavaScript projects. Its open-source community has developed templates and tools for customizing documentation.

Sphinx is mainly built for Python but also extends to other programming languages. It supports markdown and its own markup language called reStructuredText. Sphinx can create documentation in various output formats and features cross-referencing to link to other code elements.

Documentation generators are confined to the annotations they encounter across source code. Generative AI takes documentation a step further, analyzing a specific code snippet and adding code comments that describe its purpose and function. Many large language models (LLMs) for code have built-in capabilities for generating documentation.

For instance, IBM® watsonx Code Assistant™ can generate comment lines for a single method or all methods within a class. Other similar tools include GitHub Copilot, JetBrains AI Assistant, Mintlify and Tabnine.

As with any artificial intelligence system, developers must still review the outputs of AI-powered code documentation tools for completeness and accuracy.