What are your code documentation standards?

If you are anything like me then writing feels like a lot of work, but that is because code documentation requires patience and E2E know-how of the codebase. It will be difficult to start but once you begin it will be addictive and you never know what 15 min of your explanation could mean to someone else, or even to you if you have to revisit it in future.

One of the missed opportunities that come up on code documentation standards are people talking about learning styles on their teams. Some people prefer learning through conversation, some through self-study, and others through a mixture of the two. Preparing good code documentation enables the self-study type, and becomes a reference material for those who learn in a mixed style. But for those interactive learners, documentation becomes a way for the author to think out the possible questions that might be asked in interactive sessions. Being prepared leads to higher quality discussions, and can be used to prepare recordings or training materials for asynchronous learning in remote and hybrid environments.

Code documentation standards offer numerous advantages for both developers and employers. They promote cleaner, more readable code, reduce errors and technical debt, save time, facilitate collaboration, and showcase professionalism and skills to potential employers.

There are two main types of code documentation standards: internal and external. Internal documentation includes comments and annotations within the code, while external documentation includes information outside the code, like README files, API documentation, user manuals, and design documents.

Some best practices for documentation that worked on my teams include: - involving the entire team in the process - making documentation easily searchable - having a dedicated person responsible for accuracy and updates - using tools like Confluence or Notion to centralise documentation, including clear guidelines, - having a detailed and updated README for new team members.

Code documentation standards can vary, but here are some best practices to follow: 1. Write documentation alongside code for accuracy. 2. Use clear and simple language; avoid technical jargon. 3. Maintain consistent formatting and style. 4. Provide appropriate levels of detail. 5. Use examples, diagrams, or screenshots for clarity.

Code documentation standards can boost your interview performance by showcasing your commitment to code quality, best practices, and collaboration. They make it easier for interviewers to understand your code, highlighting your professionalism and competence as a developer.

Frequently engineers will try to reduce such standards to a simple checklist. I like to push back with the following questions: 1. Do people want to use your documentation? This is a sign of you being an effective communicator. If not, you need to look for flaws in your work, and be willing to accept feedback from others. 2. Does your documentation help all skills levels it needs to? Expert writing for experts is needed sometimes, but most people are trying to learn and come from different skill levels and perspectives. Can people get a handle on a concept without being a subject matter expert? 3. Does it reference other material? Cross-referencing with other materials can establish trust and confidence with all of them.

To enhance your code documentation standards: 1. Regularly review and critique your documentation for gaps, inconsistencies, and redundancies. 2. Seek feedback from peers and mentors to identify areas for improvement. 3. Analyze code and documentation from experienced developers in your field. 4. Stay current with trends and tools in code documentation and adjust your standards accordingly.

💡 Good code documents itself Using good class, function or variable names, and writing readable code reduces the need of additional and redundant documentation through comments.