Documenting Classes

Classes serve as blueprints that define the structure (attributes) and behaviors (methods) of objects, which are instances of those classes. When documenting classes, you are essentially detailing the blueprint for creating, utilizing, and deploying the class effectively.

This blueprint can come together on a unique page that captures the following:

High-level Overview – At the beginning of the class definition, a high-level overview should describe the class’s purpose, its role within the application, and any vital information about its usage. This enables users to understand what the class represents.

Class Attributes – List and describe each attribute within the class, explaining their types and purposes. This can be included in the classes high-level overview or separately in the documentation.

Methods – Each method should have a unique page that contains method signatures. These describe the purpose of the method and its parameters, return values, and any exceptions it may raise. This is critical for clarity on how to use it. More on this later.

If the class contains only a few methods, these methods and their signatures can be detailed on the same page as the class’s purpose. If several methods exist, a list of methods that link to pages providing the method signatures for each method individually can be added to the class page. It’s generally a best practice to keep the convention chosen here consistent across the documentation.

Inheritance and Relationships – If the class inherits from a parent class, mention this in the class documentation, including any overridden methods and how the class fits into the overall hierarchy.

Next, let’s learn about documenting Objects.