1. Home
  2. Writing Effective Code Documentation

Writing Effective Code Documentation

by Siddhant Bansal under the Software Quality KA.

Code documentation serves as an informative explicit and implicit reference to understanding a project. The documentation is used by existing and new stakeholders alike to identify, understand, and analyse both old and new modules for the project. It is critical for the maintenance and posterity of software engineering projects.

Classification of the Skill

Most people classify documenting code as a technical/hard skill. A person without the necessary technical expertise would not be able to effectively engineer the document and will have trouble following the standards set by the industry or organization. It does have the elements of other soft skills, particularly communication and empathy.

Empathy in Code Documentation?

Empathy is an important trait for all software engineers. Code is written by humans, for humans!

"There is a human element to making your code simple and readable. Coding with empathy means recognizing that other developers will contribute to your code down the line and making your code approachable to others." [1]

Pre-requisites of the Skill

Before writing code documentation, a deep understanding of the codebase is required. Many programming paradigms, like Don’t-Repeat-Yourself (DRY) hold true for documentation. [2] A bird’s-eye view of the software system would help classification and organization of explicit documents. Implicitly, comments and subroutine names must follow delineated standards.

  • Knowledge about how various modules function, such as APIs.
  • Coding standards followed in the project.
  • Technical writing ability.
  • Knowing what to document, why to document it, and when to document it. [3]

Like most software engineering skills, code documentation is directly affiliated to other areas including but not limited to:

  • Software Design: With relation to software design, the insight from various artifacts such as data flow diagrams and domain models is helpful in effective documentation. More about domain modelling can be found here.
  • Software Testing: Test cases need to be documented, perhaps not publicly but for internal use. Implicit documentation is an inherent part of the source code. More about testing with relation to mobile apps can be found here.
  • Software Maintenance: Apart from other activities like cost estimation while maintaining software, documentation is often considered for aiding comprehension by old and new coders alike. Any changes made are then updated in the documentation.
  • Software Quality: Code documentation is involved while measuring the quality of the software product. It acts as the bridge between the programmer and the users when direct communication is not possible.
  • Software Construction: Code documentation is ideated and updated during the implementation phase of a software project. When code is being developed for something like API Design, both implicit and explicit documentation is formed alongside it.

Rationale for Skill

Code documentation is quite an important skill since the documentation is a living entity (constantly updated and maintained) and lives for the entire lifetime of the product. For new developers and maintainers, it is a crucial tool to aid their tasks. It also serves as a reference for older developers, much like a dictionary works for a language.

An example describing implicit requirements Implicit Documentation in code can help describe what the code is doing. Intelligent naming requires programming experience.

Code documentation is very closely associated with code. This internal documentation is likely to remain accurate as and when the code is modified. [4] Most developers recognise the importance of documentation: consider trying to maintain legacy code that someone wrote a decade ago. Direct communication often is not possible in these scenarios, but the documentation that the programmer left behind would be crucial in educating the new programmers on the nuances of the system.

Can't we just document later when we need it?

The more we put off documentation, the more we accrue documentation debt... and the harder it is to pay off! [3]

Unfortunately, documentation isn't something we can procrastinate with. Code will keep growing in volume and the documentation will keep lagging behind. We must document at the same pace as the code, the two are inseparable.

The skill not only helps record information, it helps to improve overall software quality and trustworthiness. [5] It is also a good brainstorming tool which helps bring forth ideas, as well as allowing programmers to articulate those ideas effectively.

Roles for skill

Different Software Engineering roles may be involved in the process of code documentation. These can be:

  • Software Developers, working on the actual implementation.
  • Software Testers, who may be writing unit tests for the code.
  • Code Reviewers, when they realise inconsistencies in the code somewhere.
  • Software DevOps, who change the version of the deployed software in the documentation.

Anyone involved with writing the code would be involved in documenting their code in some way or the other. This can be done by naming conventions, by commenting the code, writing some form of in-code documentation like JavaDocs, or by explicitly recording things in a document.

Code documentation involves producing artifacts which can range anywhere from actual source code files to document files. A document can be special, in the sense that it is a specific kind of file or extension with associated meaning (for instance, README.md files on GitHub); or, it can be as simple as something written on a notebook.

Example of Code Documentation "Special" documentation: C# will use special XML tags to create documentation from source code at compile time. [6]

In general, documents are engineered on something more than paper even though they might start on paper. This is because documents constantly update as the project changes. There are often different versions of documentation!

Related activities are:

  • Implementation/Coding: writing new code or modifying existing code, using naming conventions etc. for self-documenting code.
  • Commenting code: could be simple comments or special comments (as described above).
  • Code Review: reviewing code written by peers or juniors to check for errors.
  • Writing test cases: which will test existing code written for a subset of potential errors.
  • Upgrading/Swapping Libraries: changing one module for another is a change that must be documented too!
  • Writing documentation: recording what changed explicitly, describing it clearly and making sure it is in one place.
  • ... and more!

Related artifacts are:

  • Source files for code
  • Documentation files (.md, .html, .xml)
  • Configuration files for the project
  • ... and more!

Real-World Example/Scenario of Skill

There is plenty to say about code documentation in the real world! To glean some insight on writing code documentation, it may help to look at what tech giants before us have been doing:

  • We can look at Oracle's Javadocs for the Java language to see how we can structure our code and what are good things to include in the documentation.
    Example of Javadocs JavaDocs give a list of methods, with signatures and a short description; clicking on them will lead to more information [7].
  • We can look at Facebook's React documentation to get an idea of what modern readable and navigable documentation looks like.
    Example of React documentation The React documentation gives us a nice navigation from any page to any part of the documentation, from Installation to an API reference [8].

In the Java example we see a sense of completeness and stability. However, the Javadocs website is not always the friendliest to use on mobile devices. Facebook's React documentation, however, does an excellent job on responsive design. It's extremely easy to find both starter tutorials and a complete API reference from the table of contents. We can learn from both of these case studies.

  • We must understand that documentation must always be consistent and clear: both of these pages clearly indicate the version of documentation and serve as a single source of truth.
  • The documentation should be readable! We notice that Javadocs tend to be dry, but they are an excellent reference. On the other hand, on mobile devices the older Javadocs are unusable and unintuitive.
  • It helps to add step-by-step guidance for the users. Both documents offer Installation/Getting Started guides. We have to consider the user's perspective (and have empathy!)

Role of Academia or Industry in Cultivating the Skill

Many big companies advocate and lead by example to encourage people to write good documentation, everywhere from their personal projects to bigger organisational projects. As an example, here is a short video on what a technical writer at Google had to say about the matter [9]:

As for leading by example, the Mozilla Developer Network (MDN) has a hugely popular web development reference which follows all the good patterns we should be mindful of with regard to code documentation.

Communities like Write the Docs help advocate documentation, teaching the development world at large about documentation and why we should care about writing it. It also provides various free resources to serve as a guide.

Tools Supporting the Skill

Thankfully for developers, there are plenty of tools to help with documentation. Many recent articles can be found which list out the most popular tools people use for documentation generation. [10]

Among them, these are good tools to start off with:

  • Read The Docs is a very popular tool used by loads of libraries and bigger projects.
  • GitHub Pages is particularly useful for documentation, since most Git repositories are hosted on GitHub anyway.
  • Javadocs can be written write within your Java codebase, and it generates good looking, navigable documentation for you automatically.

Skill Self-Assessment

I would rate myself 8/10 in Code Documentation.

In the 2+ years of industry experience, there were plenty of times I had to document code.

  • Generating documentation for legacy Perl code.
  • Writing documentation for Python cronjobs.
  • Maintaining existing documentation within the organisation.
  • Writing Knowledge Transfer documents for various React Components.
  • Writing and documenting unit test cases as a full-stack developer.
  • Writing Javadocs for a website back-end written in the Java Spring Framework.

Aside from that, I worked on many personal projects where I had the chance to explore other documentation tools and types, learning about coding standards and implicit/self-documenting code. That being said, there is always more to learn!

  • How can I automate documentation processes even more?
  • Automating tests to detect inconsistencies within documentation
  • Linting inline code documentation automatically.
  • Supporting multilingual documentation.

References

  1. Why Clean Code is Empathetic Code, by Karen White
  2. D. Spinellis, "Code Documentation," in IEEE Software, vol. 27, no. 4, pp. 18-19, July-Aug. 2010, doi: 10.1109/MS.2010.95
  3. Kamthan P., Introduction to Software Engineering Documentation
  4. Code Complete, Second Edition; Steve McConnell
  5. Andreas Goeb and Klaus Lochmann. 2011. A software quality model for SOA. In Proceedings of the 8th international workshop on Software quality (WoSQ ’11). Association for Computing Machinery, New York, NY, USA, 18–25. 10.1145/2024587.2024593
  6. Document your code with XML comments
  7. The String class reference on Javadocs
  8. React's documentation, built by Facebook
  9. Writing effective documentation | Beth Aitman | #LeadDevBerlin
  10. 18 Software Documentation Tools that Do The Hard Work For You