Documentation

Platform (Cross-Project) Documentation#

For platform documentation, this repository should be used to capture this information. Links to whimsical, platform architecture, cross-project concepts, standard design patterns used, etc should all live in this repository.

Project Documentation#

All Thanx projects should contain a top-level README that covers the following:

Project overview describing what its responsibilities are and how it fits into the Thanx platform
Set up, test, and workflow instructions
Links to high-level concept READMEs

High-level Concept Documentation#

There is a high bar for adding new high-level concepts to the codebase. For Nucleus-dependent projects, the high-level concepts may encapsulate microservices that have not yet been extracted into separate services.

Similar to the project overview, a README should be included for all high-level concepts that make up a project. These READMEs should live in the project’s subdirectory containing the logic for the given concept. These READMEs should describe responsibilities, usage, and patterns if relevant.

Examples:

Links to whimsical diagrams should ideally be included in these READMEs.

Class Documentation#

At the top of every new class, a concise description of its functionality should be included. For classes that come from Nucleus, the description should live in Nucleus. Each class should generally have a single responsibility. If you find that the class documentation for a given class is getting too long, it may be an indication that the class has too many responsibilities and should be refactored.

Public Interface Documentation#

We follow the YARD documentation syntax for documenting all public class interfaces. The public interface for a given class should be kept to a minimum. Private methods for a given class do not need to be documented. Overly verbose documentation is frowned upon - please be concise and there is no need to repeat the obvious just for the sake of following YARD standards.

Inline Documentation#

Should only be used in rare cases. Could indicate a code smell, as it usually serves to explain things that are not obvious by reading the code. Ideally these comments could be replaced by restructuring the code to make its purpose more obvious.

A good example of where inline documentation could be appropriate is when adding more context to the specific states of an AASM state machine.

Good Citizen Policy#

The codebase is not currently fully documented. As our team grows, it will become important for us to have more thorough documentation to ensure that all necessary context is easily absorbed by new team members. When you're working on a new pull request or are reviewing another team member's pull request, please uphold the guidelines outlined here. When you touch existing code, try to add docs retroactively at your own discretion. When you introduce new code, it is required to add documentation. When you see a PR come in that does not have documentation, gently remind the requester to add them.

Examples#

Abstract Class & Methods

# @abstract STI abstract class that defines expected interface for all# earn subclassesclass Program::Earn  # @abstract Subclasses should define #ensure  # def ensure  #   raise NotImplementedError  # end
  # @abstract Subclasses should define #ensure  # def issue_to(user)  #   raise NotImplementedError  # endend

PORO Doc Example

# API client that does x, y, zclass Client  # Translates the JSON configuration to raw HTML  # @param design [Hash] JSON configuration  # @return [String] Converted HTML  def render(design)    ...  end
private
  def client    ...  endend