• Homepage
• Docs
• GDPR for Developers
• 10. Good Code and …

10. Good Code and Documentation

It is important to apply good coding methods as early as possible. Readable code reduces maintenance effort and makes it easier to fix bugs over time for you and your (possible future) collaborators.

Document Code and Architecture

• Documentation is sometimes deprioritized during development due to lack of time or lack of overview of the project. However, it is crucial for the maintenance of your project: it provides an overall picture of how the code works and makes it easier to understand which parts are affected by changes.

• Document the architecture, not just the code: To maintain overview, your documentation must also explain how all components work together. Use diagrams and clear explanations.

• Maintain documentation together with the code: The best way to keep documentation up to date is to change it continuously as code changes.

• If you use source code management, you can include documentation changes in each “commit” that changes your code (see also sheet no. 4: Manage your source code).

• Don’t forget to address security in your documentation. Document the different configuration choices in your application and explain which settings are most secure.

Check the Quality of Your Code and Its Documentation

• High-quality code involves application of best practices and coding conventions that are consistently followed throughout the program. It is also recommended to follow existing conventions. Here are some examples of good practices:

  • Use explicit variable and function names so it is easy to understand what the code does at first glance.
  • Indent the code correctly so the structure is easy to read.
  • Avoid redundant code as it reduces the effort for bug fixes and reduces the risk of overlooking something.

• Tools can help you check code quality. When properly configured, they can save time by automatically ensuring compliance with coding standards. Examples of these tools include:

  • Integrated development environments (IDEs), possibly with plugins, can be configured to enforce rules for code indentation, line breaks between code blocks, placement of curly braces, etc.
  • Source code quality measurement software can identify code duplication, compliance with programming rules, and potential bugs.