Code Health

In short, Code Health is about the maintainability, readability, stability, and simplicity of code. Although there have been many efforts in the past to make code "computer friendly" in order to minimize it's size and improve performance, these are less of a concern today. This has allowed a shift in focus to the other consumers of code - developers.

As systems have become more complex and the size of teams developing them larger, the importance of having code that is easily understood and maintainable by others has become paramount. The emphasis now is writing code that others (including the original author 6 months later) can easily work on. There are a number of factors that contribute to that including:

Simplicity
Readability
Testability
Buildability

Simplicity

Code simplicity is a fairly broad topic, but at its core is about writing code that is simple in implementation and design. There are many practices that can help, but generally speaking the code should be fairly self-explanatory with few comments necessary.

Things that can contribute to simplicity are:

Descriptive function names
Descriptive variable names
Single purpose functions/methods
Avoiding nested decision trees

Readability

With the consumer focus shifting from computers to humans, there's also a shift in the need for code to be readable by developers. Readability leads to fewer errors and higher overall productivity.

Although there are many debates on the topic of code readability, it is generally well accepted that adherence to a common coding standard benefits all that work on the code. See the page Manual:Coding conventions for general standards and links to more.

Testability

The ability to test code is an important aspect of the code's overall health. It provides a mechanism by which a developer can build confidence that the changes made are working as expected and that something wasn't inadvertently broken. A code's testability speaks to the ability to easily test it. Although automation isn't itself a criteria of testability, it plays an important role in the success of testing especially in a continuous integration environment. To that end, the ability to automate the testing should be taken into consideration when measuring testability.

Buildability

It is very rare that software is written and then never again modified. For that reason, it's important to develop software with maintenance in mind.

The activity of maintaining code goes beyond just writing the code itself however. In order for a developer to effectively maintain code, they must also be able to get timely feedback on the code they are maintaining. Continuous Integration is a development pattern that supports that goal. Through the automation of code analysis, building, packaging, and testing, developers are able to get the feedback that they need in order to maintain/extend the code in a reliable and productive way.

Code Health Group

In order to support developing healthier code, the Wikimedia Foundation has created a Code Health Group which will be the steward of the software engineering processes and practices that enable both experienced and junior technical contributors to deliver high value/quality features to the various Wikimedia projects in the most productive way possible.

For more information see the Code Health Group page.

Technical Debt

Tightly coupled to code health is technical debt. A topic that is fairly prevalent within the Foundation and broader community today. Although Technical Debt can span beyond code (such as the operations tech stack), poor code health is fairly indicative of code-based technical debt. Please see the Technical Debt and Technical Debt Program pages for more information.

Newsletters

The Code Health Newsletter is a regular publication provided by the Code Health Group. It looks to share knowledge on a variety of Code Health topics. If you'd like to submit some content for the newsletter, please file a Phabricator task under the Code-Health-Newsletter project.

Below are links to past issues.