top of page

Code Maintainability: Best Practices

These best practices are designed to close common gaps in how engineers communicate through code - specifically in the areas of documentation and variable naming. These are foundational practices that support clarity, collaboration, and long-term maintainability, but they’re rarely taught in depth.

Documentation

We share 96 lessons covering how to document code effectively. The focus is on capturing why the code exists - not just what it does. This kind of context is essential for shared understanding and long-term maintainability.

​

Documentation Topics:

  • The Importance of Code Documentation 

  • Different Purposes for Comments

  • Avoiding Wasteful Comments

  • Commenting at the Appropriate Level of Abstraction

  • Written Communication

  • Comment As You Code

  • Comment Structuring

  • Commenting Code Interfaces

  • Commenting for Maintenance Programmers

  • Comment Maintenance

Variable Naming

We share 53 lessons focused entirely on naming. Clear, intentional naming helps embed product thinking directly into the code, reducing the need for extra documentation or clarification.

​

Variable Naming Topics:

  • The Importance of Variable Naming

  • Giving Names to the Unnamed

  • Naming Accuracy

  • Problem Domain Naming

  • Name Length & Specificity

  • Word Ordering

  • Word Choice

  • Units/Data Formats in Names

  • Naming Specific Kinds of Data

  • Naming Conventions

bottom of page