A guide writing maintainable code and making it easy for others to work with Last updated on May 6, 2019

Maintainable Code

A guide writing maintainable code and making it easy for others to work with



  • Semantic versioning of changes
  • Include a change log and release notes
  • Monitoring of security and deprecation issues
  • Periodic upgrades of dependencies and any improvements to the core programming language
  • Follow programming style conventions, such as by using RuboCop
  • Follow software engineering design conventions, such as those used by Ruby on Rails
  • Name variables, methods, classes, etc with names that convey what they do
  • Consider refactoring where necessary, eg with lots of nested logic or long code blocks

Easy to Use

  • Documentation describing what it is and its key features
  • Usage guidelines
  • How it works
  • Diagrams of how it works internally as well as with other systems, such as the C4 diagramming methodology

Review Best Practices

Keep up to date with developments in software development readability and maintainability.

  • Discuss ideas with colleagues and peers
  • Read official documentation of the Programming Language or framework
  • Books
  • Conferences - even if you can’t attend there are often articles and videos posted of their content, such as RailsConf
  • Contribute to open source projects that implement modern best practices, such as Ruby on Rails
  • Email lists
    • This Week in Rails
    • Thoughtbot’s blog
    • Ruby Weekly
  • Forums and Q & A websites
    • StackOverflow
    • Reddit
    • Quora
    • Hackernews