Code Health: Difference between revisions
Tags: Reverted Visual edit: Switched |
m Reverted edits by Aditya gautam (talk) to last version by JBranaa (WMF) Tag: Rollback |
||
| Line 1: | Line 1: | ||
In short, Code |
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 |
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 |
* Simplicity |
||
* Readability |
* Readability |
||
| Line 8: | Line 8: | ||
== Simplicity == |
== Simplicity == |
||
Code simplicity is a fairly broad topic, but at its core is about writing code that is simple in implementation and design. |
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: |
Things that can contribute to simplicity are: |
||
* Descriptive function names |
* Descriptive function names |
||
* Descriptive variable names |
* Descriptive variable names |
||
* Single |
* Single purpose functions/methods |
||
* Avoiding nested decision trees |
* Avoiding nested decision trees |
||
| Line 19: | Line 19: | ||
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. |
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 |
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 == |
== 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 |
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 == |
== 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. |
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 |
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 == |
== Code Health Group == |
||
In order to support developing healthier code, the Wikimedia Foundation has created a 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. |
||
[http://For%20more%20information For more information] |
|||
For more information |
For more information see the [[Code Health Group]] page. |
||
== Technical Debt == |
== Technical Debt == |
||
Latest revision as of 11:24, 7 September 2025
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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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.