The Importance of Code Documentation

While it's important to ensure your code can be easily understood and refactorable by future developers by maintaining clean code practices, there are a multitude of compelling reasons for maintaining documentation for your codebase, such as:

• An enhanced understanding, enabling developers to understand the intended logic and quickly grasp the functionality of the code.
• Better scalability having well-documented code makes it easier to add new features and adapt to changing requirements.
• Long-Term Maintenance, as your software evolves over time, your codebase documentation will serve as a guide for future developers to make better decisions about future updates.

Comparing Documentation Tools: YARD and RDoc

We specialize in Ruby on Rails monoliths and have explored options for Ruby gems that generate living, versioned documentation of ruby codebases. Of which RDoc and YARD stood out to us as potential candidates that have caught our attention. RDoc and YARD both produce HTML and command-line documentation for Ruby projects. Although these gems have many similarities and are of similar popularity ( which can be seen in the rubygem pages for rdoc and yard), there are some key differences between the two which would compel a developer to use one over the other.

Pros of Rdoc

• Simplicity: RDoc is simple and easy to use. It has a low learning curve making it a good choice for simple documentation needs.
• Low Overhead: considering that RDoc is included with Ruby, there's no need to install any additional Ruby gems to generate documentation.

Pros of Rdoc

• Limited Features: RDoc contains much less features than YARD, which may inhibit detailed documentation of your codebase.
• Visual Appeal: RDoc's default settings is considered to be less visually appealing compared to the customizability of YARD

Pros of YARD

• Local Documentation Server: YARD provides a local documentation server which includes dynamic searching of files and live reloading, allowing developers to easily preview changes to YARD documentation while working on the source code.
• Rich Documentation Features: YARD provides a variety of features that enable more detailed and expressive documentation, including support for documenting specific Ruby on Rails features.
• Yardoc Meta-tag Formatting: YARD supports tags which provide a more consistent and concise way of describing methods, classes, and modules ( similar to Python, Java, and Objective-C )

Cons of YARD

• Learning Curve: Having additional features to work with has the consequence of increasing the learning curve for beginners new to code documentation and are looking for basic documentation.
• Dependencies: Since YARD is a separate gem, it will need to be included in your project's dependencies, which will increase the complexity of your project's setup.

Given that our developers are well versed with code documentation and we highly value having a local documentation server with live reloading ( allowing us to instantly preview any changes made to the documentation ), we are inclined to choose YARD over RDoc for implementation.

Implementing YARD For Your Codebase

Start by adding the YARD gem to your project's gemfile.

Then run, bundle install to include the gem into your project.

As mentioned before, YARD has Meta-tag Formatting so you can document classes, methods, and attributes using YARD's syntax. Here's an example of a Ruby class documented using YARD syntax.

# This is a simple class that demonstrates YARD documentation.
class MyClass
  # Adds two numbers.
  #
  # @param [Integer] a The first number.
  # @param [Integer] b The second number.
  # @return [Integer] The sum of a and b.
  def add(a, b)
    a + b
  end
end

Afterwards you can generate the YARD documentation for your source code by running yardoc ( you can get a list of options by running yardoc -h ). You can view your YARD documentation by starting up local documentation server by running yard server and visiting http://localhost:8808/yardocs/MyClass.html and your documentation should look like this:

The Never-Ending Cycle Of Maintaining Code Documentation

Now that you have set up the initial documentation for your codebase, you'll need to develop regular code documentation practices to ensure that your documentation stays up-to-date. Here are some initiatives you can adopt to mitigate the challenges of maintaining code documentation:

Include Documentation as Part of Tasks: when working on a new feature, resolving a bug, or cleaning up tech debt, consider updating the documentation as part of your task. Doing so ensures that the documentation also evolves alongside the codebase.

Automatic Documentation Generation: Leverage tools like YARD and RDoc to generate documentation from your comments in the source code. Which greatly reduces the manual effort needed to ensure your documentation reflects your code accurately.

Consider integrating YARD documentation generation into your continuous integration (CI) pipeline. This ensures that documentation is generated automatically whenever code changes are pushed, further reducing the manual effort required for updating your documentation.

Documentation Culture: Develop a culture where documentation of code is treated equally as important as developing new code. By ensuring that your team is on the same page and understands the importance of maintaining documentation. Over time, keeping documentation up-to-date will naturally evolve into a habit rather than a chore.

Remember that maintaining documentation is an ongoing effort that requires commitment from the entire team. Prioritizing documentation and recognizing its role in the long-term success of a project can lead to more effective and well-maintained documentation.

Interested in joining a mission-driven team committed to improving Canada? If so, please take a moment to look at our open positions!