What is the best way to document your object oriented design for future reference?

Documenting your Object Oriented Design (OOD) can help you and others understand the structure, rationale, and behavior of your software system. It can also help you: -Identify and resolve design issues -Improve code quality -Facilitate collaboration and maintenance -Communicate your design decisions and rationale -Clarify requirements -Explain design decisions -Provide instructions for using the software application

Documenting your OOD allows you to get a high-level abstract view of the system to be designed. This allows you to understand the design decisions and any possible structural issues with the system. Remember it is far cheaper to fix design than bugs.

Documenting will be useful for you in many cases. Whether it’s avoiding duplication or getting a better understanding of the design, it’s somehow a necessity.

The critical aspect of any design documentation is visualizing the component interactions in the user journey. OOD documentation offers diagrams that can show the connections among classes, objects, sequence of events, etc. The main objective is to have traceability among all these design elements to determine which areas are impacted if any change happens. Hope this makes sense. Share your thoughts.

For effective future reference documentation of object-oriented design, combine Unified Modeling Language (UML) diagrams with detailed documentation. UML diagrams such as class diagrams, sequence diagrams, and use case diagrams visually represent the system's architecture, relationships, and interactions. Pair these diagrams with comprehensive documentation that explains the used design patterns, class responsibilities, interface descriptions, and the reasoning behind design choices. This method ensures clear communication of both structural and behavioral design aspects, aiding future developers in understanding, maintaining, and extending the system.

A great way to document your object-oriented design is to use UML (unified modeling language). This way you can visualize your design patterns more clearly.

Create documentation based on UML diagrams, and version using a git platform. You can use backstage to manage this documentation.

Here are some things you can document in your OOD: UML diagrams A standard notation for visualizing the structure and behavior of software systems. UML diagrams can show the classes, interfaces, relationships, operations, and messages that make up your OOD. README files Provide an overview and instructions for a project. They should describe the problem, solution, design, installation, usage, testing, etc. of the project. Short-form notes Capture details without interrupting your coding session flow. Keep a document open alongside your code and write down things like commands, decisions, and sources you use. Coding conventions Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.

I don't like UML. It is overly formal. I prefer simple boxes and lines drawing. I was taught the 4+1 views of software architecture, and I use that as a guiding principle for a larger design (spanning many classes and sometimes multiple repos): it may be useful to document a logical view (which classes depend on each other), process view (what talks to what at runtime), developer view(packages and components), deployment view (what is deployed to what), and as necessary walk through some scenarios. In practice, I pick and choose views.

You do not need to document everything in detail. Just focus on the things, which are needed to understand, WHY you did or want to implement it like this. - What are the most important goals of your project (reliability, compatibility or maybe performance?) - Why did you choose a strategy pattern here? - ... The fact that you are using an observer pattern here is obvious to any experienced developer. Architecture decision records (ADRs) are nice way to achieve this.

For this, you can also use free online tools and websites like “planttext”where you write your plantUML code. It’s very easy and comprehensive to use.

Here are some tips for writing documentation: Start with the problem Consider the purpose of the document. This will help determine how much content to include and how to design it. Know your readers Consider the target audience and their end goal. This can vary depending on the document, its scope, and the project or product it relates to. Document your decisions Document important points. Keep it simple Be concise and clear. Consider what details should be omitted and what information is unneeded.

Existen varias prácticas y métodos que pueden utilizarse, dependiendo tipo de proyecto, el seniority del equipo técnico y demás cuestiones de contexto. No obstante, en mi opinión, además de valerse de los diagramas necesarios de un marco como UML, resulta importantísimo tener presente dos aspectos fundamentales: 1)Trazabilidad: de manera de estar seguros de poder contemplar la explicación de todos los aspectos y componentes que hacen al dise?o y su implementación procurando no dejar nada sin especificar. 2)Validación: una vez plasmada la doc, revisarla y validarla con los actores del equipo a fin de asegurarse la calidad de la misma y evitando la faltante de especificación, no dando nada por supuesto. 3)Mantenerla y versionarla.

Document wherever developers are everyday. Link to documentation from the code, and include any diagrams directly in Confluence, tickets or wherever people are going to keep it up to date.

Here are a few best practices 1. Begin creating a document with a high-level overview that describes the purpose and goals of the object-oriented design 2. Explain the main components, their responsibilities, and how they interact. 3. Establish a consistent naming convention for your design's classes, methods, variables, and other elements. 4. Provide Class and method-level information. Use UML for document class information. 5. Document the design pattern used and why it is used 6. Creation of Document Versioning and document references 7. Keep documentation up-to-date as code evolves

Some best practices I follow: 1. Document as close to the code as possible. A line or method comment is preferable to a Confluence page. Link to Confluence if building a page, etc. 2. Document with executable code whenever possible, e.g. use tests as documentation. Much less likely to get out of date. 3. Assume any documentation outside of code is out of date (i.e. verify)

When your code extends to several thousands or tens of thousands of lines, don't anticipate significant support from automated documentation tools for ensuring its consistency and maintainability. From my experience in developing a 100,000-line OOD software piece, the primary validation process heavily relies on compilers. Therefore, selecting a language with an exceptionally strict syntax like Java becomes crucial, enabling the detection of a majority of errors. An additional advantage is the alleviation of concerns regarding duplicate declarations, even when revisiting and modifying the code several years after its initial creation.

Documenting your OOD can help you and others understand the rationale, structure, and behavior of your software system. It can also help you identify and resolve design issues, improve code quality, and facilitate collaboration and maintenance.

Based on my experience (I developed a software with 100,000 lines of OOD code), software documentation should consist of four main parts, presented as four distinct sets: 1) Reference documentation, which covers all screens and explains the meaning of each element that appears on them. 2) Documentation on getting started with the software, explaining its usage comprehensively with several complementary examples. 3) Programming documentation, which elucidates the fundamentals of software design, its architecture, and the interaction among its main components. 4) Comments embedded within the code itself, serving as supplementary information to the programming documentation.