From dc5e99fc2f7e7e785a873ae85381c2b43d710a61 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 19 Aug 2024 11:20:39 -0400 Subject: [PATCH 01/27] WIP: Initial copy of text and starting to fill in This is for betterscientificsoftware/bssw-blog-planning#35. --- ...echnicalPropertiesOfSustainableSoftware.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md new file mode 100644 index 000000000..c034ae4cd --- /dev/null +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -0,0 +1,88 @@ +# Technical Properties of Sustainable Software + +#### Contributed by [Roscoe A. Bartlett](https://github.com/bartlettroscoe) + +#### Publication date: August ???, 2024 + + +While there are many different enablers or obstacles to software sustainability, arguably, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. + + +While some authors have looked at software sustainability from mostly institutional and social perspectives (e.g. "Software sustainability - lessons learned from different disciplines"), here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of technically sustainable software. + +### Definitions of Software Sustainability + +There are various definitions of "software sustainability" in usage in the software development community. The Better Scientific Software (BSSw.io) community defines software sustainability as [???]: + +> The ability of software to continue or evolve. +> Considerations are often different when viewed from different perspectives (user, developer, manager, funder), but generally relates to resources to maintain or evolve the code, adaptability of the codebase to new uses and new computational platforms. + + + + +Weak Definition: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e. where starting from scratch would be more expensive, even in the long term). +Medium Definition: New developers can reasonably make contributions to the software but these contributions are integrated back by the original development team. +Strong Definition: A different set of developers from the original developers can take over new feature development and bug fixes and the original developers can go away (and the new team can do so cheaper than starting over from scratch). + +Extreme use case for sustainable software: Your project uses some external software package X in such a way that it would be very difficult and expensive to rip it out and/or change to use something else. At some point, the developers of package X go away and no one is left in the development community to help extend or support package X. What technical properties of package X would make it so that you could support (with reasonable cost and risk) your own usage of package X which includes activities like adding some new features, porting, and fixing bugs (that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? + +Sustainable software that satisfies the above strong definition of sustainable software and satisfies key properties listed below that are needed to enable the extreme use case for software sustainability described above can be said to be self-sustaining software since such software does not need a dedicated team to sustain the software for your continued usage. + +Key properties of sustainable software: + +The following properties are key to the sustainability of a software package according the above definition(s) of sustainable software and high quality software that contains all of these properties can be said to be self-sustaining software: + +Open Source License: Allow the user to change and use the software in any way that is needed for the success of their projects. (Note, this does not require a fully open-source license in many cases. It just has to allow your project to change the source and use the software.) +Documented history of development: Why is the software the way it is? What caused the software to be the way it currently is? (Need this to be able to understand how future changes might impact the software and possibly break existing customers.) +Core domain model distillation document: Has a clear documented core domain model which is represented in the code or a clear documented mapping of the domain model to software is given. (Need this to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes.) +Portable well-documented tests that demonstrate and protect the important behaviors of the software: These should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests. It must be made clear how to run these tests and ensure they pass or fail. These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation can not. (Need this to safely change or port the software and to understand the intended behavior of the software for usage or change.) +Clean, logical and understandable code interfaces and implementation (i.e. self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other good design and implementation principles) (Need this to be able to change and extend the software at low cost.) +Well-defined and well-regulated internal and external dependencies: The less code you have to configure and build, the easier it will be to modify and fix if you have to do so. (Need this to avoid having to support the build and support lots of code that you don’t need.) +All upstream dependencies are also sustainable software (stopping at standard tools like standard compilers and other ubiquitous tools and libraries that are guaranteed to be sustained and supported over the long term). + +Key practices that enable or help lead to the creation of sustainable software: + +Development and Collaboration Workflows practices: +If you want to share development and deployment between several developers and customers, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. +If you want to include/encourage peer contributions, use an open-source software development platform that facilitates this (e.g. GitHub, GitLab, BitBucket, etc.) +Clean Understandable Code Practices: +Favor languages that are more widely known and/or well supported over confusing or less well-known languages. +Use domain-driven design for the key interfaces and implementation details. +Strive for self-documenting code (i.e. reduce the need for extra documentation that typically does not get maintained). +Reduce or eliminate code duplication (to avoid complicating future changes) +Reduce software complexity (e.g. deep nested control structures, deep inheritance hierarchies) +Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. +Testing Practices: +Favor verification and acceptance tests over no-change regression tests (???reference???). +Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). +Make the reason for why a test passes or fails obvious from the output of the test without having to open a debugger or add extra print statements. +Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). +Building and Running Tests Practices: +Use build and tests systems that are better known and/or supported that can create portable builds on all target platforms (e.g. CMake and CTest) +Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g. CTest and CDash). +Set up automated builds that run tests before integrating changes to the main development branch (e.g. CI builders that are linked into GitHub or GitLab). + + + + + + +ToDo: + +* Mention pulls (user demand, unique features, not easy to duplicate, little-to-no competition, high surface areas interaction with the code,...) and pushes for software sustainability + +* Fast build and test runtimes that allow using free services like GitHub Actions and GitLab CI is a huge bonus. (Expense jobs massively complicates the sustainability + + + + + +### Author bio + +Roscoe A. Bartlett ??? + + From ef9e86e255d18e74121c0f945730a4ca89e0caa2 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 19 Aug 2024 12:44:17 -0400 Subject: [PATCH 02/27] WIP: Finished basic formatting of copied text I also added a little more text. --- ...echnicalPropertiesOfSustainableSoftware.md | 130 +++++++++++++----- 1 file changed, 95 insertions(+), 35 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index c034ae4cd..b465fcb83 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -10,61 +10,116 @@ While there are many different enablers or obstacles to software sustainability, While some authors have looked at software sustainability from mostly institutional and social perspectives (e.g. "Software sustainability - lessons learned from different disciplines"), here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of technically sustainable software. -### Definitions of Software Sustainability -There are various definitions of "software sustainability" in usage in the software development community. The Better Scientific Software (BSSw.io) community defines software sustainability as [???]: +### Definitions of Sustainable Software + +There are various definitions of "software sustainability" in usage in the software development community. +The Better Scientific Software (BSSw.io) community defines software sustainability as[bssw-ss]: > The ability of software to continue or evolve. > Considerations are often different when viewed from different perspectives (user, developer, manager, funder), but generally relates to resources to maintain or evolve the code, adaptability of the codebase to new uses and new computational platforms. +and as[bssw-whatis-ss]: + +> Sustainable software means that an existing product remains viable in the future such that it makes sense to continue using, adapting, and expanding its capabilities instead of replacing it with another new or existing product. + +and: + +> Sustainability is a measure of the cost to maintain and improve a product over its lifetime. + +It is this latter focus on the "cost to maintain and improve" the software over time that we will focus on in this article. + +With this latter cost/feasibility focus in mind, we define different levels of **Technically Sustainable Software**: + +* **Weak Definition of Sustainable Software**: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e. where starting from scratch would be more expensive, even in the long term). + +* **Medium Definition of Sustainable Software**: New developers can reasonably make contributions to the software but these contributions are integrated back by the original development team. + +* **Strong Definition of Sustainable Software**: A different set of developers from the original developers can take over new feature development and bug fixes and the original developers can go away (and the new team can do so cheaper than starting over from scratch). + +At the extreme end of the "Strong Definition" is the **Extreme uses case for Sustainable software**: +Your project uses some external software package X in such a way that it would be very difficult and expensive to rip it out and/or change to use something else. +At some point, the developers of package X go away and no one is left in the development community to help extend or support package X. +What technical properties of package X would make it so that you could continue support (with reasonable cost and risk) your own project's usage of package X which includes activities like adding some new features, porting, and fixing bugs (i.e. that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? + +Software that satisfies key technical properties listed below would tend to meet the Strong Definition of Sustainable Software and enable the extreme use case for software sustainability described above. +Such software could be said to be **Self-Sustaining Software** since such software does not need a dedicated team to sustain the software for your (limited) continued usage. +### Key Technical Properties of Sustainable Software -Weak Definition: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e. where starting from scratch would be more expensive, even in the long term). -Medium Definition: New developers can reasonably make contributions to the software but these contributions are integrated back by the original development team. -Strong Definition: A different set of developers from the original developers can take over new feature development and bug fixes and the original developers can go away (and the new team can do so cheaper than starting over from scratch). +The following technical properties have been widely recognized to lead to software that less expensive to maintain according the above definition(s) of sustainable software. +High quality software that contains all of these properties can be said to be self-sustaining software: -Extreme use case for sustainable software: Your project uses some external software package X in such a way that it would be very difficult and expensive to rip it out and/or change to use something else. At some point, the developers of package X go away and no one is left in the development community to help extend or support package X. What technical properties of package X would make it so that you could support (with reasonable cost and risk) your own usage of package X which includes activities like adding some new features, porting, and fixing bugs (that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? +**Open Source License**: +Allow the user to change and use the software in any way that is needed for the success of their projects. +(Note, this does not require a fully open-source license in many cases. +It just has to allow your project to change the source and use the software.) -Sustainable software that satisfies the above strong definition of sustainable software and satisfies key properties listed below that are needed to enable the extreme use case for software sustainability described above can be said to be self-sustaining software since such software does not need a dedicated team to sustain the software for your continued usage. +**Documented history of development**: +Why is the software the way it is? +What caused the software to be the way it currently is? +(Need this to be able to understand how future changes might impact the software and possibly break existing customers.) -Key properties of sustainable software: +**Core domain model distillation document**: +Has a clear documented core domain model which is represented in the code or a clear documented mapping of the domain model to software is given. +(Need this to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes.) -The following properties are key to the sustainability of a software package according the above definition(s) of sustainable software and high quality software that contains all of these properties can be said to be self-sustaining software: +* **Portable, well-documented, robust tests that demonstrate and protect the important behaviors of the software**: +These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests. +It must be made clear how to run these tests and ensure they pass or fail. +These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. +(Need this to safely change or port the software and to understand the intended behavior of the software for usage or change.) -Open Source License: Allow the user to change and use the software in any way that is needed for the success of their projects. (Note, this does not require a fully open-source license in many cases. It just has to allow your project to change the source and use the software.) -Documented history of development: Why is the software the way it is? What caused the software to be the way it currently is? (Need this to be able to understand how future changes might impact the software and possibly break existing customers.) -Core domain model distillation document: Has a clear documented core domain model which is represented in the code or a clear documented mapping of the domain model to software is given. (Need this to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes.) -Portable well-documented tests that demonstrate and protect the important behaviors of the software: These should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests. It must be made clear how to run these tests and ensure they pass or fail. These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation can not. (Need this to safely change or port the software and to understand the intended behavior of the software for usage or change.) -Clean, logical and understandable code interfaces and implementation (i.e. self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other good design and implementation principles) (Need this to be able to change and extend the software at low cost.) -Well-defined and well-regulated internal and external dependencies: The less code you have to configure and build, the easier it will be to modify and fix if you have to do so. (Need this to avoid having to support the build and support lots of code that you don’t need.) -All upstream dependencies are also sustainable software (stopping at standard tools like standard compilers and other ubiquitous tools and libraries that are guaranteed to be sustained and supported over the long term). +**Clean, logical and understandable code interfaces and implementation**: +This includes self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known good design and implementation principles. -Key practices that enable or help lead to the creation of sustainable software: +**Fast building code and fast running test suite**: +An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and the tests and then to run the test suites. ???ToDo: Finish??? -Development and Collaboration Workflows practices: -If you want to share development and deployment between several developers and customers, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. -If you want to include/encourage peer contributions, use an open-source software development platform that facilitates this (e.g. GitHub, GitLab, BitBucket, etc.) -Clean Understandable Code Practices: -Favor languages that are more widely known and/or well supported over confusing or less well-known languages. -Use domain-driven design for the key interfaces and implementation details. -Strive for self-documenting code (i.e. reduce the need for extra documentation that typically does not get maintained). -Reduce or eliminate code duplication (to avoid complicating future changes) +**Well-defined and well-regulated internal and external dependencies**: +Reuse and sustainability are greatly aided by minimizing external dependencies and having dependencies on software package with good design and build modularity. +For example, even if your project only depends on small piece of a large software package, if that smaller piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software as you port to new platforms. +The less code you have to configure and build, the easier it will be to modify and fix if you have to do so. +(Need this to avoid having to support the build and support lots of code that you don’t need.) + +* **All upstream dependencies are also sustainable software**: +If any of the upstream dependencies of a software package are not sustainable software, then the downstream packages cannot be sustainable either. +(That is, a chain is only as strong as its weakest link.) +This recursive requirement only stops at standard tools like standard compilers and other ubiquitous tools and libraries that are guaranteed to be sustained and supported over the long term. +This requirement is also another motivation for minimizing external dependencies. + +Therefore, the technical requirements for sustainable software are quite strict and difficult to achieve for many software projects. + + +### Detailed practices and properties of sustainable software + +While this article as been focused on the technical properties of the software itself, there are key practices that can aid in the creating and maintenance of sustainable software. + +**Development and Collaboration Workflows practices:** +* If you want to share development and deployment between several developers and customers, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. +* If you want to include/encourage peer contributions, use an open-source software development platform that facilitates this (e.g. GitHub, GitLab, BitBucket, etc.) + +**Clean Understandable Code Practices:** +* Favor languages that are more widely known and/or well supported over confusing or less well-known languages. +* Use domain-driven design for the key interfaces and implementation details. +* Strive for self-documenting code (i.e. reduce the need for extra documentation that typically does not get maintained). +* Reduce or eliminate code duplication (to avoid complicating future changes) Reduce software complexity (e.g. deep nested control structures, deep inheritance hierarchies) Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. -Testing Practices: -Favor verification and acceptance tests over no-change regression tests (???reference???). -Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). -Make the reason for why a test passes or fails obvious from the output of the test without having to open a debugger or add extra print statements. -Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). -Building and Running Tests Practices: -Use build and tests systems that are better known and/or supported that can create portable builds on all target platforms (e.g. CMake and CTest) -Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g. CTest and CDash). -Set up automated builds that run tests before integrating changes to the main development branch (e.g. CI builders that are linked into GitHub or GitLab). - +**Testing Practices:** +* Favor verification and acceptance tests over no-change regression tests (???reference???). +* Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). +* Make the reason for why a test passes or fails obvious from the output of the test without having to open a debugger or add extra print statements. +* Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). +**Building and Running Tests Practices:** +* Use build and tests systems that are better known and/or supported that can create portable builds on all target platforms (e.g. CMake and CTest) +* Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g. CTest and CDash). +* Set up automated builds that run tests before integrating changes to the main development branch (e.g. CI builders that are linked into GitHub or GitLab). +### Summary ToDo: @@ -74,6 +129,11 @@ ToDo: * Fast build and test runtimes that allow using free services like GitHub Actions and GitLab CI is a huge bonus. (Expense jobs massively complicates the sustainability + + +[bssw-ss]: https://bssw.io/items?topic=software-sustainability "BSSw: Software Sustainability" + +[bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" From 3e1c928a1c0e2b1a391dcc040e71af06b997375d Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 19 Aug 2024 17:21:27 -0400 Subject: [PATCH 03/27] Finished first fairly complete draft I still need to fill in some references and then I can do some more detailed editing. According to emails "count-words", this is currently 1935 words long. (The target is about 1500 so this could use some editing to reduce length.) --- ...echnicalPropertiesOfSustainableSoftware.md | 65 ++++++++++++------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index b465fcb83..9909fc88e 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -27,7 +27,7 @@ and: > Sustainability is a measure of the cost to maintain and improve a product over its lifetime. -It is this latter focus on the "cost to maintain and improve" the software over time that we will focus on in this article. +It is this latter concentration on the "cost to maintain and improve" software over time will be the focus in this article. With this latter cost/feasibility focus in mind, we define different levels of **Technically Sustainable Software**: @@ -53,32 +53,37 @@ High quality software that contains all of these properties can be said to be se **Open Source License**: Allow the user to change and use the software in any way that is needed for the success of their projects. -(Note, this does not require a fully open-source license in many cases. -It just has to allow your project to change the source and use the software.) +Note, this does not require a fully open-source license in many cases. +It just has to allow your project to change the source and use the software as needed. **Documented history of development**: -Why is the software the way it is? -What caused the software to be the way it currently is? -(Need this to be able to understand how future changes might impact the software and possibly break existing customers.) +The development history of the software (which can be captured in the version-control history and linked issue trackers) can answer many questions that are important to the future of the software. +What factors caused the software to be in its current state? +What requirements went into the development of the software? (Might some of those requirements and features no longer be necessary for future versions of the software to allow breaking some backward compatibility?) **Core domain model distillation document**: -Has a clear documented core domain model which is represented in the code or a clear documented mapping of the domain model to software is given. -(Need this to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes.) +Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given? +Need document is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. * **Portable, well-documented, robust tests that demonstrate and protect the important behaviors of the software**: -These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests. +These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests [???]. It must be made clear how to run these tests and ensure they pass or fail. +The reason for why a test passes or fails must be obvious from the output of the test without having to open a debugger or add extra print statements. These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. -(Need this to safely change or port the software and to understand the intended behavior of the software for usage or change.) +These tests are needed to safely change or port the software and to understand the intended behavior of the software for future usage or change. **Clean, logical and understandable code interfaces and implementation**: -This includes self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known good design and implementation principles. +Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles. **Fast building code and fast running test suite**: -An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and the tests and then to run the test suites. ???ToDo: Finish??? +An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and the tests and then to run the test suites. +A software package that requires significant computational resources to test the code after any change represents a huge type of technical debt that must be carried around by future maintainers of the package. +Alternatively, software that builds fairly fast and where the tests can be run in a smaller amount of time can take advantage of free cloud continuous testing services. +(At the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with various limits on the computational cost.) +However, software that is very computationally expensive to build and test, or requires special hardware like GPUs, can impose a huge burden on the sustainability of such software in the need to procure, setup, and maintain the needed computing resources. **Well-defined and well-regulated internal and external dependencies**: -Reuse and sustainability are greatly aided by minimizing external dependencies and having dependencies on software package with good design and build modularity. +Reuse and sustainability are greatly aided by minimizing external dependencies and having the internal dependencies of the software package itself established using good design and build modularity. For example, even if your project only depends on small piece of a large software package, if that smaller piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software as you port to new platforms. The less code you have to configure and build, the easier it will be to modify and fix if you have to do so. (Need this to avoid having to support the build and support lots of code that you don’t need.) @@ -92,26 +97,29 @@ This requirement is also another motivation for minimizing external dependencies Therefore, the technical requirements for sustainable software are quite strict and difficult to achieve for many software projects. -### Detailed practices and properties of sustainable software +### Some key practices for creating and maintaining sustainable software -While this article as been focused on the technical properties of the software itself, there are key practices that can aid in the creating and maintenance of sustainable software. +While this article as been focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software. **Development and Collaboration Workflows practices:** -* If you want to share development and deployment between several developers and customers, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. -* If you want to include/encourage peer contributions, use an open-source software development platform that facilitates this (e.g. GitHub, GitLab, BitBucket, etc.) +* For shared development, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. +* To encourage peer contributions, use an open-source software development platform that facilitates these workflows (e.g. GitHub, GitLab, BitBucket, etc.) + +**Requirements collection and maintenance:** +* Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible argument. +* Create well structured and well documented version control (i.e. Git) commits for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g. issue trackers). **Clean Understandable Code Practices:** * Favor languages that are more widely known and/or well supported over confusing or less well-known languages. * Use domain-driven design for the key interfaces and implementation details. * Strive for self-documenting code (i.e. reduce the need for extra documentation that typically does not get maintained). -* Reduce or eliminate code duplication (to avoid complicating future changes) -Reduce software complexity (e.g. deep nested control structures, deep inheritance hierarchies) -Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. +* Reduce or eliminate code duplication (to avoid complicating future changes). +* Reduce software complexity (e.g. deep nested control structures, deep inheritance hierarchies) +* Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. **Testing Practices:** * Favor verification and acceptance tests over no-change regression tests (???reference???). * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). -* Make the reason for why a test passes or fails obvious from the output of the test without having to open a debugger or add extra print statements. * Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). **Building and Running Tests Practices:** @@ -119,15 +127,23 @@ Continuously refactor the code while adding new features and fixing bugs to main * Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g. CTest and CDash). * Set up automated builds that run tests before integrating changes to the main development branch (e.g. CI builders that are linked into GitHub or GitLab). + ### Summary +The technical properties of a software package and its upstream dependencies can have a major impact in reducing the cost to maintain and extend a given software package. +In some cases, software can be sufficiently clean, well-tested, well-structured, and documented, and with minimal enough upstream dependencies that it can be reasonable sustained by any motivated developer, even if the originating development team and/or origination goes away. +This is the extreme form of sustainable software approaches the idea of ***self-sustaining software*** and should be the goal for many key software packages in the software system. +In identifying these desirable technical properties, projects can structure development processes that produce and maintain these desirable properties. + -ToDo: + + @@ -135,11 +151,14 @@ ToDo: [bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" +[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "'Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability' in 'Software Engineering for Science' {Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. November 3, 2016}" ### Author bio -Roscoe A. Bartlett ??? +Roscoe A. Bartlett earned his PhD in chemical engineering from Carnegie Mellon University researching numerical approaches for solving large-scale constrained optimization problems applied to chemical process engineering. +At Sandia National Laboratories and Oak Ridge National Laboratory, he continued research and development in constrained optimization, sensitivity methods, and large-scale numerical software design and integration for computational science & engineering (CSE). +Dr. Bartlett currently focuses on software engineering challenges in CSE as well as the development of build, test, and integration software and processes for CSE. @@ -164,6 +166,6 @@ Dr. Bartlett currently focuses on software engineering challenges in CSE as well From fa6193bcb927cb5005b9a73a6fec37b95562bcfd Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 05:52:34 -0400 Subject: [PATCH 07/27] Add a missing reference --- .../Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 7541aed2d..ed0631fa1 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -8,7 +8,7 @@ While there are many different enablers or obstacles to software sustainability, arguably, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. -While some authors have looked at software sustainability from mostly institutional and social perspectives (e.g. "Software sustainability - lessons learned from different disciplines"), here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of technically sustainable software. +While some authors have looked at software sustainability from mostly institutional and social perspectives[ssi-ss-2018], here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software. @@ -157,6 +157,8 @@ In identifying these desirable technical properties, projects can structure deve [se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "'Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability' in 'Software Engineering for Science' {Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. November 3, 2016}" +[ssi-ss-2018]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" + ### Author bio From c66dfbce6780aa5b54ba44b76aae2dd95241d22a Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 05:55:02 -0400 Subject: [PATCH 08/27] WIP: Move references to bottom The tool wikize-refs.py is refusing the recognise the usage of the reference [se2s-book-2016]. Perhaps this will help? --- ...echnicalPropertiesOfSustainableSoftware.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index ed0631fa1..a8a060e20 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -149,17 +149,6 @@ In identifying these desirable technical properties, projects can structure deve ---> - - -[bssw-ss]: https://bssw.io/items?topic=software-sustainability "BSSw: Software Sustainability" - -[bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" - -[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "'Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability' in 'Software Engineering for Science' {Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. November 3, 2016}" - -[ssi-ss-2018]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" - - ### Author bio Roscoe A. Bartlett earned his PhD in chemical engineering from Carnegie Mellon University researching numerical approaches for solving large-scale constrained optimization problems applied to chemical process engineering. @@ -171,3 +160,14 @@ Publish: Yes Track: Deep Dive Topics: Software sustainability ---> + + + + +[bssw-ss]: https://bssw.io/items?topic=software-sustainability "BSSw: Software Sustainability" + +[bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" + +[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "'Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability' in 'Software Engineering for Science' {Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. November 3, 2016}" + +[ssi-ss-2018]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" From 47e2792645728aeb47f3d09ea8d2ca99e1caae27 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 06:07:40 -0400 Subject: [PATCH 09/27] Fix reference link for [se2s-book-2016] The error was confusing but I misspelled one usage --- .../2024-08-TechnicalPropertiesOfSustainableSoftware.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index a8a060e20..21a4fec5f 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -68,7 +68,7 @@ Has a clear documented core domain model (which is represented in the code or a Need document is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. * **Portable, well-documented, robust tests that demonstrate and protect the important behaviors of the software**: -These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests[e2s-book-2016] +These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests.[se2s-book-2016] It must be made clear how to run these tests and ensure they pass or fail. The reason for why a test passes or fails must be obvious from the output of the test without having to open a debugger or add extra print statements. These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. @@ -120,7 +120,7 @@ While this article as been focused on the technical properties of the software i * Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. **Testing Practices:** -* Favor verification and acceptance tests over no-change regression tests[se2s-book-2016]. +* Favor verification and acceptance tests over no-change regression tests.[se2s-book-2016] * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). * Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). @@ -168,6 +168,6 @@ Topics: Software sustainability [bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" -[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "'Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability' in 'Software Engineering for Science' {Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. November 3, 2016}" +[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability{Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016}" [ssi-ss-2018]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" From ca707b4cf563c55fadc78d72df93d3b445b99dda Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 06:08:59 -0400 Subject: [PATCH 10/27] Run wikize_refs.py on references This messed up the numbering and the links. But I can fix those manually in the next commit. I will not run this script on the file after this. --- ...echnicalPropertiesOfSustainableSoftware.md | 36 ++++++++++++------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 21a4fec5f..a38590f84 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -8,7 +8,7 @@ While there are many different enablers or obstacles to software sustainability, arguably, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. -While some authors have looked at software sustainability from mostly institutional and social perspectives[ssi-ss-2018], here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software. +While some authors have looked at software sustainability from mostly institutional and social perspectives[4], here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software. @@ -16,12 +16,12 @@ While some authors have looked at software sustainability from mostly institutio ### Definitions of Sustainable Software There are various definitions of "software sustainability" in usage in the software development community. -The Better Scientific Software (BSSw.io) community defines software sustainability as[bssw-ss]: +The Better Scientific Software (BSSw.io) community defines software sustainability as[1]: > The ability of software to continue or evolve. > Considerations are often different when viewed from different perspectives (user, developer, manager, funder), but generally relates to resources to maintain or evolve the code, adaptability of the codebase to new uses and new computational platforms. -and as[bssw-whatis-ss]: +and as[2]: > Sustainable software means that an existing product remains viable in the future such that it makes sense to continue using, adapting, and expanding its capabilities instead of replacing it with another new or existing product. @@ -68,7 +68,7 @@ Has a clear documented core domain model (which is represented in the code or a Need document is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. * **Portable, well-documented, robust tests that demonstrate and protect the important behaviors of the software**: -These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests.[se2s-book-2016] +These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests.[3] It must be made clear how to run these tests and ensure they pass or fail. The reason for why a test passes or fails must be obvious from the output of the test without having to open a debugger or add extra print statements. These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. @@ -120,7 +120,7 @@ While this article as been focused on the technical properties of the software i * Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. **Testing Practices:** -* Favor verification and acceptance tests over no-change regression tests.[se2s-book-2016] +* Favor verification and acceptance tests over no-change regression tests.[3] * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). * Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). @@ -164,10 +164,22 @@ Topics: Software sustainability -[bssw-ss]: https://bssw.io/items?topic=software-sustainability "BSSw: Software Sustainability" - -[bssw-whatis-ss]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" - -[se2s-book-2016]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability{Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016}" - -[ssi-ss-2018]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" +[bssw-ss-sfer-ezikiw]: https://bssw.io/items?topic=software-sustainability "BSSw: Software Sustainability" + +[bssw-whatis-ss-sfer-ezikiw]: https://bssw.io/items/what-is-software-sustainability "BSSw: What is Software Sustainability?" + +[se2s-book-2016-sfer-ezikiw]: https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability{Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016}" + +[ssi-ss-2018-sfer-ezikiw]: https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines "Software Sustainability — Lessons Learned from Different Disciplines {Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018}" + +[1]: #sfer-ezikiw-1 "BSSw: Software Sustainability" +[2]: #sfer-ezikiw-2 "BSSw: What is Software Sustainability?" +[3]: #sfer-ezikiw-3 "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability" +[4]: #sfer-ezikiw-4 "Software Sustainability — Lessons Learned from Different Disciplines" + +### References + +* 2[BSSw: Software Sustainability](https://bssw.io/items?topic=software-sustainability) +* 3[BSSw: What is Software Sustainability?](https://bssw.io/items/what-is-software-sustainability) +* 4[Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability
Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016](https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju) +* 5[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) From 0ab4728aa7cf847665458466563455ba3ef0d4ee Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 06:16:29 -0400 Subject: [PATCH 11/27] Manually fix off-by-one reference numbering error caused by wikize-refs.py No sure what happened here but it was easy enough to fix manually. The tool wikize-refs.py needs more unit testing and test cases. --- ...2024-08-TechnicalPropertiesOfSustainableSoftware.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index a38590f84..62b25088b 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -142,8 +142,6 @@ In identifying these desirable technical properties, projects can structure deve * Mention pulls (user demand, unique features, not easy to duplicate, little-to-no competition, high surface areas interaction with the code,...) and pushes for software sustainability? => May not have room for this. Article is already too long! -* Run wikize_refs.py ... - * Do detailed editing with Grammarly.com ... ---> @@ -179,7 +177,7 @@ Topics: Software sustainability ### References -* 2[BSSw: Software Sustainability](https://bssw.io/items?topic=software-sustainability) -* 3[BSSw: What is Software Sustainability?](https://bssw.io/items/what-is-software-sustainability) -* 4[Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability
Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016](https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju) -* 5[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) +* 1[BSSw: Software Sustainability](https://bssw.io/items?topic=software-sustainability) +* 2[BSSw: What is Software Sustainability?](https://bssw.io/items/what-is-software-sustainability) +* 3[Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability
Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016](https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju) +* 4[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) From a6ae730ad4921ab9c93a91bdcef71a980744bd96 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 20 Aug 2024 07:13:09 -0400 Subject: [PATCH 12/27] Full edit using Grammarly NOTE: I also added some missing reference placeholders [???] in case I want to add those. --- ...echnicalPropertiesOfSustainableSoftware.md | 112 +++++++++--------- 1 file changed, 57 insertions(+), 55 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 62b25088b..9566a71bd 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -5,17 +5,17 @@ #### Publication date: August ???, 2024 -While there are many different enablers or obstacles to software sustainability, arguably, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. +While there are many different enablers or obstacles to software sustainability, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. -While some authors have looked at software sustainability from mostly institutional and social perspectives[4], here, we consider key technical properties of the software itself that helps to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software. +While some authors have looked at software sustainability from primarily institutional and social perspectives[4], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. ### Definitions of Sustainable Software -There are various definitions of "software sustainability" in usage in the software development community. +Various definitions of "software sustainability" exist in the software development community. The Better Scientific Software (BSSw.io) community defines software sustainability as[1]: > The ability of software to continue or evolve. @@ -29,113 +29,115 @@ and: > Sustainability is a measure of the cost to maintain and improve a product over its lifetime. -It is this latter concentration on the "cost to maintain and improve" software over time will be the focus in this article. +This article will focus on reducing the "cost to maintain and improve" software over time and on software's technical properties that enable sustainability. With this latter cost/feasibility focus in mind, we define different levels of **Technically Sustainable Software**: -* **Weak Definition of Sustainable Software**: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e. where starting from scratch would be more expensive, even in the long term). +* **Weak Definition of Sustainable Software**: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e., where starting from scratch would be more expensive, even in the long term). * **Medium Definition of Sustainable Software**: New developers can reasonably make contributions to the software but these contributions are integrated back by the original development team. -* **Strong Definition of Sustainable Software**: A different set of developers from the original developers can take over new feature development and bug fixes and the original developers can go away (and the new team can do so cheaper than starting over from scratch). +* **Strong Definition of Sustainable Software**: A different set of developers from the original developers can take over new feature development and bug fixes, and the original developers can go away (and the new team can do so cheaper than starting over from scratch). -At the extreme end of the "Strong Definition" is the **Extreme uses case for Sustainable software**: -Your project uses some external software package X in such a way that it would be very difficult and expensive to rip it out and/or change to use something else. -At some point, the developers of package X go away and no one is left in the development community to help extend or support package X. -What technical properties of package X would make it so that you could continue support (with reasonable cost and risk) your own project's usage of package X which includes activities like adding some new features, porting, and fixing bugs (i.e. that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? +The ultimate instance of the "Strong Definition" is the **Extreme uses case for Sustainable software**: +Your project uses some external software Package X in such a way that it would be very difficult and expensive to rip it out and/or change the code to use something else. +At some point, the developers of Package X go away, and no one is left in the development community to help extend or support Package X. +What technical properties of Package X would make it so that you could continue support (with reasonable cost and risk) your own project's usage of Package X, which includes activities like adding some new features, porting to new platforms and compilers, and fixing bugs (i.e., that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? -Software that satisfies key technical properties listed below would tend to meet the Strong Definition of Sustainable Software and enable the extreme use case for software sustainability described above. -Such software could be said to be **Self-Sustaining Software** since such software does not need a dedicated team to sustain the software for your (limited) continued usage. +Software that satisfies the key technical properties listed below would tend to meet the Strong Definition of Sustainable Software and enable the extreme use case for software sustainability described above. +Smaller or extremely well-structured software packages that possess these technical properties could be said to be **Self-Sustaining Software** since such software does not need a dedicated team to sustain it for your (limited) continued usage. You could sufficiently sustain it yourself. ### Key Technical Properties of Sustainable Software The following technical properties have been widely recognized to lead to software that less expensive to maintain according the above definition(s) of sustainable software. -High quality software that contains all of these properties can be said to be self-sustaining software: **Open Source License**: Allow the user to change and use the software in any way that is needed for the success of their projects. -Note, this does not require a fully open-source license in many cases. -It just has to allow your project to change the source and use the software as needed. +Note that this does not require a fully open-source license in many cases. +The license just has to allow your project to change the source and use the software as needed for your project. **Documented history of development**: The development history of the software (which can be captured in the version-control history and linked issue trackers) can answer many questions that are important to the future of the software. What factors caused the software to be in its current state? -What requirements went into the development of the software? (Might some of those requirements and features no longer be necessary for future versions of the software to allow breaking some backward compatibility?) +What requirements went into the development of the software? +(Might some of those requirements and features no longer be necessary for future versions of the software which would allow breaking some backward compatibility?) **Core domain model distillation document**: -Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given? -Need document is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. +Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given? [???] +This document and model is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. -* **Portable, well-documented, robust tests that demonstrate and protect the important behaviors of the software**: -These tests should give the key use cases and embody the requirements of the code and not be just simple no-change regression tests.[3] +* **Portable, well-documented, robust tests**: +that demonstrate and protect the important behaviors of the software +These tests should give the key use cases and embody the requirements of the code that demonstrate and protect the important behaviors of the software +These should not just be simple no-change regression tests that don't actually reveal the intent of the software.[3] It must be made clear how to run these tests and ensure they pass or fail. -The reason for why a test passes or fails must be obvious from the output of the test without having to open a debugger or add extra print statements. -These tests can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. -These tests are needed to safely change or port the software and to understand the intended behavior of the software for future usage or change. +The reason for why a test passes or fails must be obvious from the output of the test (without having to open a debugger or add extra print statements). +Quality tests like these can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. +These tests are needed to safely change or port the software and to understand the intended behavior of the software to support future usage or changes. -**Clean, logical and understandable code interfaces and implementation**: -Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles. +**Clean, logical, and understandable code interfaces and implementation**: +Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles. [???] **Fast building code and fast running test suite**: -An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and the tests and then to run the test suites. -A software package that requires significant computational resources to test the code after any change represents a huge type of technical debt that must be carried around by future maintainers of the package. -Alternatively, software that builds fairly fast and where the tests can be run in a smaller amount of time can take advantage of free cloud continuous testing services. -(At the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with various limits on the computational cost.) -However, software that is very computationally expensive to build and test, or requires special hardware like GPUs, can impose a huge burden on the sustainability of such software in the need to procure, setup, and maintain the needed computing resources. +An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and tests and then run the test suite. +A software package that requires significant computational resources to test the code after any change represents a huge technical debt that must be carried around by future maintainers and sponsors of the software package. +Alternatively, software that builds relatively quickly and where the tests can be run in less time can take advantage of free cloud continuous testing services. +(For example, at the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with various limits on the computational loads supported.) +However, software that is very computationally expensive to build and test or requires special hardware (like GPUs) can impose a huge burden on its sustainability in the need to procure, set up, and maintain the computing resources and DevOps infrastructure needed to utilize them. **Well-defined and well-regulated internal and external dependencies**: -Reuse and sustainability are greatly aided by minimizing external dependencies and having the internal dependencies of the software package itself established using good design and build modularity. -For example, even if your project only depends on small piece of a large software package, if that smaller piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software as you port to new platforms. -The less code you have to configure and build, the easier it will be to modify and fix if you have to do so. -(Need this to avoid having to support the build and support lots of code that you don’t need.) +Reuse and sustainability are greatly aided by minimizing external dependencies and having well-structured internal dependencies of the software package itself established using good design and build modularity. +For example, even if your project only depends on small piece of a large software package, if that smaller piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software as you port to new platforms and perform other maintence tasks. +The less code you have to configure and build, the easier it will be to modify. * **All upstream dependencies are also sustainable software**: -If any of the upstream dependencies of a software package are not sustainable software, then the downstream packages cannot be sustainable either. -(That is, a chain is only as strong as its weakest link.) +If any of the upstream dependencies of a software package do not also have these key technical properties of sustainable software, then the downstream packages cannot be sustainable either. +(A chain is only as strong as its weakest link.) This recursive requirement only stops at standard tools like standard compilers and other ubiquitous tools and libraries that are guaranteed to be sustained and supported over the long term. This requirement is also another motivation for minimizing external dependencies. -Therefore, the technical requirements for sustainable software are quite strict and difficult to achieve for many software projects. +These technical requirements for sustainable software are quite strict and difficult to achieve for many software projects. +But the rewards of doing so can be substantial. ### Some key practices for creating and maintaining sustainable software -While this article as been focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software. +While this article has focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software that possess these technical properties. -**Development and Collaboration Workflows practices:** +**Development and Collaboration Workflows Practices:** * For shared development, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. -* To encourage peer contributions, use an open-source software development platform that facilitates these workflows (e.g. GitHub, GitLab, BitBucket, etc.) +* To encourage peer contributions, use an open-source software development platform that facilitates these workflows (e.g., GitHub, GitLab, BitBucket) -**Requirements collection and maintenance:** +**Requirements Collection and Maintenance:** * Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible argument. -* Create well structured and well documented version control (i.e. Git) commits for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g. issue trackers). +* Create well-structured and well-documented version control (i.e. Git) commits and commit messages for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g., issue trackers). **Clean Understandable Code Practices:** * Favor languages that are more widely known and/or well supported over confusing or less well-known languages. -* Use domain-driven design for the key interfaces and implementation details. -* Strive for self-documenting code (i.e. reduce the need for extra documentation that typically does not get maintained). -* Reduce or eliminate code duplication (to avoid complicating future changes). -* Reduce software complexity (e.g. deep nested control structures, deep inheritance hierarchies) -* Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code and other good code properties. +* Use domain-driven design for the key interfaces and implementation details. [???] +* Strive for self-documenting code (i.e., reduce the need for extra documentation that typically does not get maintained). +* Reduce or eliminate code duplication. +* Reduce software complexity (e.g. deeply nested control structures, deep inheritance hierarchies) +* Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code, tests, and documentation. **Testing Practices:** * Favor verification and acceptance tests over no-change regression tests.[3] * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). -* Invest is making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). +* Invest in making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). **Building and Running Tests Practices:** -* Use build and tests systems that are better known and/or supported that can create portable builds on all target platforms (e.g. CMake and CTest) -* Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g. CTest and CDash). -* Set up automated builds that run tests before integrating changes to the main development branch (e.g. CI builders that are linked into GitHub or GitLab). +* Use build and test systems that are better known and/or supported that can create portable builds and run tests on all target platforms (e.g., CMake and CTest) +* Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g., CTest and CDash). +* Set up automated builds that run tests before integrating changes to the main development branch (e.g., use continuous integration builders that are integrated into GitHub or GitLab). ### Summary -The technical properties of a software package and its upstream dependencies can have a major impact in reducing the cost to maintain and extend a given software package. -In some cases, software can be sufficiently clean, well-tested, well-structured, and documented, and with minimal enough upstream dependencies that it can be reasonable sustained by any motivated developer, even if the originating development team and/or origination goes away. -This is the extreme form of sustainable software approaches the idea of ***self-sustaining software*** and should be the goal for many key software packages in the software system. -In identifying these desirable technical properties, projects can structure development processes that produce and maintain these desirable properties. +The technical properties of a software package and its upstream dependencies can have a major impact on reducing the cost of maintaining and extending a given software package. +In some cases, the software can be sufficiently clean, well-tested, well-structured, and documented, and with minimal enough upstream dependencies that it can be reasonably sustained by any motivated developer, even if the originating development team and/or origination disappear. +This is the extreme form of sustainable software that approaches the ideal of ***Self-Sustaining Software*** and should be the goal for many essential software packages in a software ecosystem. +In identifying these desirable technical properties, projects can adopt and adapt development processes that produce and maintain these desirable technical properties. [1]: #sfer-ezikiw-1 "BSSw: Software Sustainability" [2]: #sfer-ezikiw-2 "BSSw: What is Software Sustainability?" [3]: #sfer-ezikiw-3 "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability" [4]: #sfer-ezikiw-4 "Software Sustainability — Lessons Learned from Different Disciplines" +[5]: #sfer-ezikiw-5 "Domain Driven Design" +[6]: #sfer-ezikiw-6 "Clean Code" +[7]: #sfer-ezikiw-7 "Code Complete: 2nd Edition" ### References @@ -179,3 +183,6 @@ Topics: Software sustainability * 2[BSSw: What is Software Sustainability?](https://bssw.io/items/what-is-software-sustainability) * 3[Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability
Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016](https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju) * 4[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) +* 5[Domain Driven Design
Eric Evans, Addison Wesley, 2004](https://martinfowler.com/bliki/DomainDrivenDesign.html) +* 6[Clean Code - A Handbook of Agile Software Craftsmanship
Robert Martin, Prentice Hall, 2009, ISBN-13: 978-0-13-235088-4, ISBN-10: 0-13-235088-2](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) +* 7[Code Complete: Second Edition: A Practical Handbook of Software Construction
Steve McConnell, 2009, ISBN: 9780735619678](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) From d121ef2711ec17721040af3b2c98c38ea7685973 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Thu, 22 Aug 2024 10:13:25 -0400 Subject: [PATCH 16/27] Add bullet on code review --- .../Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 449ff8015..88ae94cf7 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -116,6 +116,7 @@ While this article has focused on the technical properties of the software itsel * Reduce or eliminate code duplication. * Reduce software complexity (e.g. deeply nested control structures, deep inheritance hierarchies) * Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code, tests, and documentation. +* Have all changes to the code, tests, or documentation reviewed by at least on other developer. **Testing Practices:** * Favor verification and acceptance tests over no-change regression tests.[3] From d21f5b6a30f5e776a2a474719ecff4b4f7622525 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 26 Aug 2024 09:54:03 -0400 Subject: [PATCH 17/27] Add bullets for usage of more tools, update references I added mentions of code formatters and other tools like static analyzers and runtime memory checkers, as suggested by @ksbeattie. I also changed the reference from the book chapter "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability" to shorter articles on the bssw.io site itself. (We should likely reference that book chapter in those other bssw.io articles.) I also added another reference related to testing and had to shift all of the latter references. (I could not use wikize-refs.py to do this because of the off-by-one issue.) --- ...echnicalPropertiesOfSustainableSoftware.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 88ae94cf7..cad3b266f 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -8,7 +8,7 @@ While there are many different enablers or obstacles to software sustainability, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. -While some authors have looked at software sustainability from primarily institutional and social perspectives[4], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. +While some authors have looked at software sustainability from primarily institutional and social perspectives[5], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. @@ -59,7 +59,7 @@ What requirements went into the development of the software? (Might some of those requirements and features no longer be necessary for future versions of the software which would allow breaking some backward compatibility?) **Core domain model distillation document**: -Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given?[5] +Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given?[6] This document and model is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. **Portable, well-documented, robust tests**: @@ -72,7 +72,7 @@ Quality tests like these can take the place of a lot of documentation that one w These tests are needed to safely change or port the software and to understand the intended behavior of the software to support future usage or changes. **Clean, logical, and understandable code interfaces and implementation**: -Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles.[6],[7] +Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles.[7],[8] **Fast building code and fast running test suite**: An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and tests and then run the test suite. @@ -99,7 +99,7 @@ In addition, smaller (or extremely well-structured) software packages that posse ### Some Key Practices for Creating and Maintaining Sustainable Software -While this article has focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software that possess these technical properties.[6],[7] +While this article has focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software that possess these technical properties.[7],[8] **Development and Collaboration Workflows Practices:** * For shared development, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. @@ -114,14 +114,16 @@ While this article has focused on the technical properties of the software itsel * Use domain-driven design for the key interfaces and implementation details.[5] * Strive for self-documenting code (i.e., reduce the need for extra documentation that typically does not get maintained). * Reduce or eliminate code duplication. -* Reduce software complexity (e.g. deeply nested control structures, deep inheritance hierarchies) +* Reduce software complexity (e.g., deeply nested control structures, deep inheritance hierarchies). +* Use automatic code formatting tools (e.g., `clang-format`). * Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code, tests, and documentation. * Have all changes to the code, tests, or documentation reviewed by at least on other developer. **Testing Practices:** -* Favor verification and acceptance tests over no-change regression tests.[3] +* Favor verification and acceptance tests over no-change regression tests.[4] * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). * Invest in making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). +* Use static analyzers (e.g., Clang-Tidy) and runtime memory checkers (e.g., Clang address/memory/leak sanitizers)[3] **Building and Running Tests Practices:** * Use build and test systems that are better known and/or supported that can create portable builds and run tests on all target platforms (e.g., CMake and CTest) @@ -172,18 +174,20 @@ Topics: Software sustainability [1]: #sfer-ezikiw-1 "BSSw: Software Sustainability" [2]: #sfer-ezikiw-2 "BSSw: What is Software Sustainability?" -[3]: #sfer-ezikiw-3 "Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability" -[4]: #sfer-ezikiw-4 "Software Sustainability — Lessons Learned from Different Disciplines" -[5]: #sfer-ezikiw-5 "Domain Driven Design" -[6]: #sfer-ezikiw-6 "Clean Code" -[7]: #sfer-ezikiw-7 "Code Complete: 2nd Edition" +[3]: #sfer-ezikiw-3 "BSSw: How to Improve Testing for CSE Software" +[4]: #sfer-ezikiw-4 "BSSw: Definition and Categorization of Tests for CSE Software" +[5]: #sfer-ezikiw-5 "Software Sustainability — Lessons Learned from Different Disciplines" +[6]: #sfer-ezikiw-6 "Domain Driven Design" +[7]: #sfer-ezikiw-7 "Clean Code" +[8]: #sfer-ezikiw-8 "Code Complete: 2nd Edition" ### References * 1[BSSw: Software Sustainability](https://bssw.io/items?topic=software-sustainability) * 2[BSSw: What is Software Sustainability?](https://bssw.io/items/what-is-software-sustainability) -* 3[Testing of Scientific Software: Impacts on Research Credibility, Development Productivity, Maturation, and Sustainability
Bartlett, Roscoe A., Anshu Dubey, Xiaoye Sherry Li, J. David Moulton, James W. Willenbring, and Ulrike M. Yang. Software Engineering for Science. November 3, 2016](https://www.routledge.com/Software-Engineering-for-Science/Carver-ChueHong-Thiruvathukal/p/book/9780367574277?srsltid=AfmBOorz50aK1Mkuti9WCQOMdLz8QPohQpMnZw3HLsxcrYWHuGEyKvju) -* 4[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) -* 5[Domain Driven Design
Eric Evans, Addison Wesley, 2004](https://martinfowler.com/bliki/DomainDrivenDesign.html) -* 6[Clean Code - A Handbook of Agile Software Craftsmanship
Robert Martin, Prentice Hall, 2009, ISBN-13: 978-0-13-235088-4, ISBN-10: 0-13-235088-2](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) -* 7[Code Complete: Second Edition: A Practical Handbook of Software Construction
Steve McConnell, 2009, ISBN: 9780735619678](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) +* 3[BSSw: How to Improve Testing for CSE Software](https://bssw.io/blog_posts/how-to-improve-testing-for-cse-software) +* 4[BSSw: Definition and Categorization of Tests for CSE Software](https://bssw.io/blog_posts/definition-and-categorization-of-tests-for-cse-software) +* 5[Software Sustainability — Lessons Learned from Different Disciplines
Neil Chue Hong, HPC Best Practices Seminar Series, August 21, 2018](https://bssw.io/events/webinar-software-sustainability-lessons-learned-from-different-disciplines) +* 6[Domain Driven Design
Eric Evans, Addison Wesley, 2004](https://martinfowler.com/bliki/DomainDrivenDesign.html) +* 7[Clean Code - A Handbook of Agile Software Craftsmanship
Robert Martin, Prentice Hall, 2009, ISBN-13: 978-0-13-235088-4, ISBN-10: 0-13-235088-2](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) +* 8[Code Complete: Second Edition: A Practical Handbook of Software Construction
Steve McConnell, 2009, ISBN: 9780735619678](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) From e7d2750f492beb18a852cdee213ca2db61cffe8d Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 26 Aug 2024 10:01:09 -0400 Subject: [PATCH 18/27] Update info on software licenses Added some more text as suggested in review by @ksbeattie. I also added a reference for more info on picking an open-source software license. --- .../2024-08-TechnicalPropertiesOfSustainableSoftware.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index cad3b266f..97e88ce57 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -49,8 +49,11 @@ The following technical properties have been widely recognized to lead to softwa **Open Source License**: Allow the user to change and use the software in any way that is needed for the success of their projects. -Note that this does not require a fully open-source license in many cases. +Note that this does not require a fully open-source license in many cases (e.g., such as with export controlled or ITAR software). The license just has to allow your project to change the source and use the software as needed for your project. +Picking an software license can be a tricky task and every open-source license is not equivalent. +For example, some open-source licenses like the GNU Public License (GPL), and its variations, can actually restrict the maintenance and usage of the software in many cases. +Software licensing can be complex and requires careful consideration.[9] **Documented history of development**: The development history of the software (which can be captured in the version-control history and linked issue trackers) can answer many questions that are important to the future of the software. @@ -180,6 +183,7 @@ Topics: Software sustainability [6]: #sfer-ezikiw-6 "Domain Driven Design" [7]: #sfer-ezikiw-7 "Clean Code" [8]: #sfer-ezikiw-8 "Code Complete: 2nd Edition" +[9]: #sfer-ezikiw-9 "BSSw: An Introduction to Choosing an Open Source Code License" ### References @@ -191,3 +195,4 @@ Topics: Software sustainability * 6[Domain Driven Design
Eric Evans, Addison Wesley, 2004](https://martinfowler.com/bliki/DomainDrivenDesign.html) * 7[Clean Code - A Handbook of Agile Software Craftsmanship
Robert Martin, Prentice Hall, 2009, ISBN-13: 978-0-13-235088-4, ISBN-10: 0-13-235088-2](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) * 8[Code Complete: Second Edition: A Practical Handbook of Software Construction
Steve McConnell, 2009, ISBN: 9780735619678](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) +* 9[BSSw: An Introduction to Choosing an Open Source Code License](https://bssw.io/items/an-introduction-to-choosing-an-open-source-code-license) \ No newline at end of file From ed72a8238655e5c8943b21aff99821458674a8f9 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Mon, 26 Aug 2024 10:06:33 -0400 Subject: [PATCH 19/27] Update text about core domain model documentation Improving this text was suggested by @ksbeattie in his review. --- .../2024-08-TechnicalPropertiesOfSustainableSoftware.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 97e88ce57..103502f07 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -61,9 +61,9 @@ What factors caused the software to be in its current state? What requirements went into the development of the software? (Might some of those requirements and features no longer be necessary for future versions of the software which would allow breaking some backward compatibility?) -**Core domain model distillation document**: -Has a clear documented core domain model (which is represented in the code or a clear documented mapping of the domain model to software) been given?[6] -This document and model is needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. +**Clear documented architecture and goals**: +Has a clear core domain model and architecture for the software been documented (which is represented in the code or a clear documented mapping of the domain model to software)?[6] +This document and domain model are needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. **Portable, well-documented, robust tests**: that demonstrate and protect the important behaviors of the software From ddbed24566f391fc8fd2ce9db631785ece5c50c7 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Sat, 31 Aug 2024 13:14:58 -0400 Subject: [PATCH 20/27] Slated for September 2024 publication Just need to fill in the day on Sept this gets published --- .../Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 103502f07..01802cfdd 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -2,7 +2,7 @@ #### Contributed by [Roscoe A. Bartlett](https://github.com/bartlettroscoe) -#### Publication date: August ???, 2024 +#### Publication date: September ???, 2024 While there are many different enablers or obstacles to software sustainability, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. @@ -195,4 +195,4 @@ Topics: Software sustainability * 6[Domain Driven Design
Eric Evans, Addison Wesley, 2004](https://martinfowler.com/bliki/DomainDrivenDesign.html) * 7[Clean Code - A Handbook of Agile Software Craftsmanship
Robert Martin, Prentice Hall, 2009, ISBN-13: 978-0-13-235088-4, ISBN-10: 0-13-235088-2](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) * 8[Code Complete: Second Edition: A Practical Handbook of Software Construction
Steve McConnell, 2009, ISBN: 9780735619678](https://github.com/martinmurciego/good-books/blob/master/Clean%20Code_%20A%20Handbook%20of%20Agile%20Software%20Craftsmanship%20-%20Robert%20C.%20Martin.pdf) -* 9[BSSw: An Introduction to Choosing an Open Source Code License](https://bssw.io/items/an-introduction-to-choosing-an-open-source-code-license) \ No newline at end of file +* 9[BSSw: An Introduction to Choosing an Open Source Code License](https://bssw.io/items/an-introduction-to-choosing-an-open-source-code-license) From 9285e5d025560f5e92bf348596f9d4deb1b88319 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Sun, 1 Sep 2024 17:17:48 -0400 Subject: [PATCH 21/27] More edits I noticed a few things after letting this sit for several days, including a few typos that Grammarly.com missed. --- ...echnicalPropertiesOfSustainableSoftware.md | 92 ++++++++++--------- 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 01802cfdd..655f2118d 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -29,18 +29,21 @@ and: > Sustainability is a measure of the cost to maintain and improve a product over its lifetime. -With this latter cost/feasibility focus in mind, we define three different **Levels of Sustainable Software**: +With this latter viability/cost perspective in mind, we define three different **Levels of Sustainable Software**: * **Weak Definition**: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e., where starting from scratch would be more expensive, even in the long term). -* **Medium Definition**: New developers can reasonably make contributions to the software but these contributions are integrated back by the original development team. +* **Medium Definition**: New developers can reasonably make contributions to the software, but these contributions are integrated back by the original development team. * **Strong Definition**: A different set of developers from the original developers can take over new feature development and bug fixes, and the original developers can go away (and the new team can do so cheaper than starting over from scratch). The ultimate instance of the "Strong Definition" is the **Extreme Use Case for Sustainable Software**: -Your project uses some external software Package X in such a way that it would be very difficult and expensive to rip it out and/or change the code to use something else. + +> Your project uses some external software Package X in such a way that it would be very difficult and expensive to rip it out and/or change the code to use something else. At some point, the developers of Package X go away, and no one is left in the development community to help extend or support Package X. -What technical properties of Package X would make it so that you could continue support (with reasonable cost and risk) your own project's usage of Package X, which includes activities like adding some new features, porting to new platforms and compilers, and fixing bugs (i.e., that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? +Therefore, your project is forced to sustain software Package X for its own usage for a reasonable time horizon. + +What technical properties of Package X would make it so that your project could continue to sustain (with reasonable cost and risk) your own project's usage of Package X, which includes activities like adding some new features, porting to new platforms and compilers, and fixing bugs (i.e., that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? ### Key Technical Properties of Sustainable Software @@ -49,9 +52,9 @@ The following technical properties have been widely recognized to lead to softwa **Open Source License**: Allow the user to change and use the software in any way that is needed for the success of their projects. -Note that this does not require a fully open-source license in many cases (e.g., such as with export controlled or ITAR software). +Note that this does not always require a fully open-source license in many cases (e.g., such as with export controlled or ITAR software). The license just has to allow your project to change the source and use the software as needed for your project. -Picking an software license can be a tricky task and every open-source license is not equivalent. +Picking a software license can be a tricky task and every open-source license is not equivalent. For example, some open-source licenses like the GNU Public License (GPL), and its variations, can actually restrict the maintenance and usage of the software in many cases. Software licensing can be complex and requires careful consideration.[9] @@ -59,35 +62,35 @@ Software licensing can be complex and requires careful consideration.[9][6] +A clear core domain model and architecture for the software as been documented (which is represented in the code or a clear documented mapping of the domain model to software)?[6] This document and domain model are needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. -**Portable, well-documented, robust tests**: -that demonstrate and protect the important behaviors of the software -These tests should give the key use cases and embody the requirements of the code that demonstrate and protect the important behaviors of the software -These should not just be simple no-change regression tests that don't actually reveal the intent of the software.[3] -It must be made clear how to run these tests and ensure they pass or fail. +**Strong, portable, well-documented and robust tests**: +The software package has strong and robust unit, integration, and system-level tests that demonstrate and protect the important behaviors of the software.[4] +These tests should give the key use cases and embody the requirements of the code that demonstrate and protect the important features of the software. +These should primarily be verification and acceptance tests, instead of no-change regression tests that don't actually reveal the intent of the software.[3] +It must be made clear how to run the test suites and ensure they have a clear pass or fail. The reason for why a test passes or fails must be obvious from the output of the test (without having to open a debugger or add extra print statements). -Quality tests like these can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change where standard documentation cannot. +Quality tests like these can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change to the code (where standard documentation cannot). These tests are needed to safely change or port the software and to understand the intended behavior of the software to support future usage or changes. **Clean, logical, and understandable code interfaces and implementation**: Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles.[7],[8] **Fast building code and fast running test suite**: -An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and tests and then run the test suite. -A software package that requires significant computational resources to test the code after any change represents a huge technical debt that must be carried around by future maintainers and sponsors of the software package. +An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and tests, and to run the test suite(s). +A software package that requires significant computational resources to rebuild and test the code after any change represents a huge technical debt that must be carried around by future maintainers and sponsors of the software package. +Software that is very computationally expensive to build and test, or requires special hardware (like GPUs), can impose a huge burden on its sustainability in the need to procure, set up, and maintain the computing resources and DevOps infrastructure needed to utilize them. Alternatively, software that builds relatively quickly and where the tests can be run in less time can often take advantage of free cloud continuous testing services. -(For example, at the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with various limits on the computational loads supported.) -However, software that is very computationally expensive to build and test or requires special hardware (like GPUs) can impose a huge burden on its sustainability in the need to procure, set up, and maintain the computing resources and DevOps infrastructure needed to utilize them. +(For example, at the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with relatively tight limits on the computational loads.) **Well-defined and well-regulated internal and external dependencies**: Reuse and sustainability are greatly aided by minimizing external dependencies and having well-structured internal dependencies within the software package itself (established using good design and build modularity). -For example, even if your project only depends on small piece of a large external software package, if that smaller piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software as you port to new platforms and perform other maintenance tasks. -The less code you have to configure and build, the easier it will be to sustain if needed. +For example, even if your project only depends on small piece of a large external software package, if that smaller external piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software that you never use as you port to new platforms and perform other maintenance tasks. +The less code you have to configure and build, the easier it is to sustain if needed. **All upstream dependencies are also sustainable software**: If any of the upstream dependencies of a software package do not also have these key technical properties of sustainable software, then the downstream dependent packages cannot be sustainable. @@ -95,58 +98,57 @@ If any of the upstream dependencies of a software package do not also have these This recursive requirement only stops at standard tools like major compilers and other ubiquitous tools and libraries that are guaranteed to be sustained and supported over the long term. (This requirement is also another motivation for minimizing external dependencies.) -Software that satisfies key technical properties listed above would tend to meet the Strong Definition of sustainable software defined above. -In addition, smaller (or extremely well-structured) software packages that possess these technical properties could be considered **Self-Sustaining Software** since such software does not need a dedicated team to sustain it for your (limited) continued usage. -(If needed, you could sustain such a package yourself for your usage at a reasonable cost.) +Software that satisfies the key technical properties listed above would tend to meet the **Strong Definition** of sustainable software. +In addition, especially smaller or extremely well-structured software packages that strongly possess these technical properties could be considered **Self-Sustaining Software**, since such software should not need a dedicated team to sustain it for your project's (limited) continued usage. +(If needed, you could sustain such an upstream package yourself for your project's usage at a reasonable cost.) ### Some Key Practices for Creating and Maintaining Sustainable Software -While this article has focused on the technical properties of the software itself, there are key practices that can aid in the creation and maintenance of sustainable software that possess these technical properties.[7],[8] +While this article has focused on the technical properties of the software itself, there are several key practices[7],[8] that can aid in the creation and maintenance of sustainable software that possess these technical properties, including some of the following. **Development and Collaboration Workflows Practices:** * For shared development, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. -* To encourage peer contributions, use an open-source software development platform that facilitates these workflows (e.g., GitHub, GitLab, BitBucket) +* To encourage peer contributions, use an open-source software development platform that facilitates collaborative workflows (e.g., GitHub, GitLab, BitBucket). -**Requirements Collection and Maintenance:** -* Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible argument. -* Create well-structured and well-documented version control (i.e. Git) commits and commit messages for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g., issue trackers). +**Requirements Tracking Practices:** +* Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible rational. +* Create well-structured and well-documented version control (i.e., Git) commits for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g., issue trackers). -**Clean Understandable Code Practices:** -* Favor languages that are more widely known and/or well-supported over languages that are more confusing and/or less well-known. +**Clean Understandable Coding Practices:** +* Favor languages that are more widely known and/or well-supported. * Use domain-driven design for the key interfaces and implementation details.[5] * Strive for self-documenting code (i.e., reduce the need for extra documentation that typically does not get maintained). * Reduce or eliminate code duplication. -* Reduce software complexity (e.g., deeply nested control structures, deep inheritance hierarchies). -* Use automatic code formatting tools (e.g., `clang-format`). * Continuously refactor the code while adding new features and fixing bugs to maintain or improve the code, tests, and documentation. -* Have all changes to the code, tests, or documentation reviewed by at least on other developer. +* Reduce software complexity (e.g., deeply nested control structures, deep inheritance hierarchies, etc.). +* Use automatic code formatting tools (e.g., Clang-Format). +* Use static analysis tools to enforce coding standards (e.g., Clang-Tidy). +* Have all changes to the code, tests, or documentation reviewed by at least on other knowledgeable developer (focusing on issues that cannot be found and enforced by automated tools like Clang-Format and Clang-Tidy). **Testing Practices:** * Favor verification and acceptance tests over no-change regression tests.[4] -* Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with better code coverage and better feature coverage than tests that get written after the code is written). -* Invest in making tests run as fast as possible (expensive tests are a significant form of technical debt to a software project). -* Use static analyzers (e.g., Clang-Tidy) and runtime memory checkers (e.g., Clang address/memory/leak sanitizers)[3] +* Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with higher code coverage and feature coverage than tests that get created after the code is written). +* Invest in making tests run as fast as possible (expensive tests are a significant form of technical debt). +* Use static analyzers (e.g., Clang-Tidy) and runtime memory checkers (e.g., Clang address/memory/leak sanitizers)[3] to look for software defects. -**Building and Running Tests Practices:** -* Use build and test systems that are better known and/or supported that can create portable builds and run tests on all target platforms (e.g., CMake and CTest) +**DevOps Practices:** +* Use build and test systems that are better known and/or supported that can create portable builds (e.g., CMake) and run tests on all target platforms (e.g., CTest). * Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g., CTest and CDash). -* Set up automated builds that run tests before integrating changes to the main development branch (e.g., use continuous integration builders that are integrated into GitHub or GitLab). +* Set up automated builds that run tests before integrating changes to the main development branch (e.g., use continuous integration frameworks that are integrated into GitHub or GitLab). ### Summary -The technical properties of a software package and its upstream dependencies can have a major impact on reducing the cost of maintaining and extending a given software package. -In some cases, the software can be sufficiently clean, well-tested, well-structured, and documented, and with minimal enough upstream dependencies that it can be reasonably sustained by any motivated developer, even if the originating development team and/or origination disappear. +Some key technical properties of a software package (and its upstream dependencies) can have major impact on reducing the cost of maintaining and extending a given software package, and therefore improving its sustainability. +In some cases, the software can be sufficiently clean, well-tested, well-structured, and well-documented, and with minimal-enough upstream dependencies, that it can be reasonably sustained by any motivated developer; even if the originating development team and/or organization disappear. This is the extreme form of sustainable software that approaches the ideal of ***Self-Sustaining Software*** and should be the goal for many essential software packages in a software ecosystem. -In identifying these desirable technical properties, projects can adopt and adapt development processes that produce and maintain these desirable technical properties. +In identifying these desirable technical properties, projects can adopt and adapt development processes that help to produce and maintain these desirable technical properties. From d3381906b6a17223172cd7b7c10ecfbce357efe2 Mon Sep 17 00:00:00 2001 From: "David E. Bernholdt" <426409+bernhold@users.noreply.github.com> Date: Thu, 26 Sep 2024 15:33:51 -0400 Subject: [PATCH 22/27] Edit pass, preparing for publication --- ...24-08-TechnicalPropertiesOfSustainableSoftware.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md index 655f2118d..18dca8f90 100644 --- a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md @@ -2,7 +2,7 @@ #### Contributed by [Roscoe A. Bartlett](https://github.com/bartlettroscoe) -#### Publication date: September ???, 2024 +#### Publication date: September 27, 2024 While there are many different enablers or obstacles to software sustainability, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. @@ -37,7 +37,7 @@ With this latter viability/cost perspective in mind, we define three different * * **Strong Definition**: A different set of developers from the original developers can take over new feature development and bug fixes, and the original developers can go away (and the new team can do so cheaper than starting over from scratch). -The ultimate instance of the "Strong Definition" is the **Extreme Use Case for Sustainable Software**: +The ultimate instance of the "Strong Definition" is the **Extreme Use Case for Sustainable Software**: > Your project uses some external software Package X in such a way that it would be very difficult and expensive to rip it out and/or change the code to use something else. At some point, the developers of Package X go away, and no one is left in the development community to help extend or support Package X. @@ -64,8 +64,8 @@ What factors caused the software to be in its current state? What requirements went into the development of the software? (Might some of those requirements and features no longer be necessary for future versions of the software, which would allow breaking some backward compatibility?) -**Clear documented architecture and goals**: -A clear core domain model and architecture for the software as been documented (which is represented in the code or a clear documented mapping of the domain model to software)?[6] +**Clearly documented architecture and goals**: +A clear core domain model and architecture for the software has been documented (which is represented in the code or a clear documented mapping of the domain model to software)?[6] This document and domain model are needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. **Strong, portable, well-documented and robust tests**: @@ -74,7 +74,7 @@ These tests should give the key use cases and embody the requirements of the cod These should primarily be verification and acceptance tests, instead of no-change regression tests that don't actually reveal the intent of the software.[3] It must be made clear how to run the test suites and ensure they have a clear pass or fail. The reason for why a test passes or fails must be obvious from the output of the test (without having to open a debugger or add extra print statements). -Quality tests like these can take the place of a lot of documentation that one would otherwise need to write and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change to the code (where standard documentation cannot). +Quality tests like these can take the place of a lot of documentation that one would otherwise need to write, and such tests are, in a way, better than more standard documentation since automated tests are always checked after every change to the code (where standard documentation cannot). These tests are needed to safely change or port the software and to understand the intended behavior of the software to support future usage or changes. **Clean, logical, and understandable code interfaces and implementation**: @@ -112,7 +112,7 @@ While this article has focused on the technical properties of the software itsel * To encourage peer contributions, use an open-source software development platform that facilitates collaborative workflows (e.g., GitHub, GitLab, BitBucket). **Requirements Tracking Practices:** -* Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible rational. +* Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible rationale. * Create well-structured and well-documented version control (i.e., Git) commits for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g., issue trackers). **Clean Understandable Coding Practices:** From a7cafa295210cdba250fac31269b09cef8098c9e Mon Sep 17 00:00:00 2001 From: "David E. Bernholdt" <426409+bernhold@users.noreply.github.com> Date: Thu, 26 Sep 2024 15:35:36 -0400 Subject: [PATCH 23/27] Update filename --- ...are.md => 2024-09-TechnicalPropertiesOfSustainableSoftware.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Articles/Blog/{2024-08-TechnicalPropertiesOfSustainableSoftware.md => 2024-09-TechnicalPropertiesOfSustainableSoftware.md} (100%) diff --git a/Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md similarity index 100% rename from Articles/Blog/2024-08-TechnicalPropertiesOfSustainableSoftware.md rename to Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md From 94259815e120c97dc50e626e8f4dbad11dc3fbd7 Mon Sep 17 00:00:00 2001 From: "David E. Bernholdt" <426409+bernhold@users.noreply.github.com> Date: Thu, 26 Sep 2024 16:52:14 -0400 Subject: [PATCH 24/27] Try image as hero --- .../2024-09-TechnicalPropertiesOfSustainableSoftware.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md index 18dca8f90..0015ca7ae 100644 --- a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md @@ -1,5 +1,9 @@ # Technical Properties of Sustainable Software +**Hero Image:** + +- + #### Contributed by [Roscoe A. Bartlett](https://github.com/bartlettroscoe) #### Publication date: September 27, 2024 @@ -10,7 +14,9 @@ While there are many different enablers or obstacles to software sustainability, While some authors have looked at software sustainability from primarily institutional and social perspectives[5], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. + ### Definitions of Sustainable Software From 7bd11380c618ea77a3869657c1d326679c5dfc63 Mon Sep 17 00:00:00 2001 From: "David E. Bernholdt" <426409+bernhold@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:10:41 -0400 Subject: [PATCH 25/27] Not the right aspect ratio for a hero --- .../2024-09-TechnicalPropertiesOfSustainableSoftware.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md index 0015ca7ae..5723cadb7 100644 --- a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md @@ -1,9 +1,5 @@ # Technical Properties of Sustainable Software -**Hero Image:** - -- - #### Contributed by [Roscoe A. Bartlett](https://github.com/bartlettroscoe) #### Publication date: September 27, 2024 @@ -14,10 +10,7 @@ While there are many different enablers or obstacles to software sustainability, While some authors have looked at software sustainability from primarily institutional and social perspectives[5], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. - - ### Definitions of Sustainable Software From 2791eac351a5064cef67518968f326f229a5befa Mon Sep 17 00:00:00 2001 From: Lois Curfman McInnes Date: Fri, 27 Sep 2024 07:45:20 -0400 Subject: [PATCH 26/27] Update 2024-09-TechnicalPropertiesOfSustainableSoftware.md minor edits --- ...echnicalPropertiesOfSustainableSoftware.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md index 5723cadb7..768849a7e 100644 --- a/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md +++ b/Articles/Blog/2024-09-TechnicalPropertiesOfSustainableSoftware.md @@ -8,7 +8,7 @@ While there are many different enablers or obstacles to software sustainability, some of the most important are related to the technical properties of the software itself, independent of any individual developer, development team, user community, or funding source. -While some authors have looked at software sustainability from primarily institutional and social perspectives[5], here, we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. +While some authors have looked at software sustainability from primarily institutional and social perspectives,[5] here we consider vital technical properties of the software itself that help to improve sustainability and some development practices that aid in the creation and maintenance of sustainable software with these technical properties. @@ -18,7 +18,7 @@ Various definitions of "software sustainability" exist in the software developme The Better Scientific Software (BSSw.io) community defines software sustainability as[1]: > The ability of software to continue or evolve. -> Considerations are often different when viewed from different perspectives (user, developer, manager, funder), but generally relates to resources to maintain or evolve the code, adaptability of the codebase to new uses and new computational platforms. +> Considerations often differ when viewed from various perspectives (user, developer, manager, funder), but generally relate to resources to maintain or evolve the code, as well as adaptability of the codebase to new uses and new computational platforms. and as[2]: @@ -28,15 +28,15 @@ and: > Sustainability is a measure of the cost to maintain and improve a product over its lifetime. -With this latter viability/cost perspective in mind, we define three different **Levels of Sustainable Software**: +With this latter viability/cost perspective in mind, we define three different **levels of sustainable software**: -* **Weak Definition**: The same team of developers that originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e., where starting from scratch would be more expensive, even in the long term). +* **Weak definition**: The same team of developers who originally created the software can continue to add new features and fix bugs in the software at a reasonable cost (i.e., where starting from scratch would be more expensive, even in the long term). -* **Medium Definition**: New developers can reasonably make contributions to the software, but these contributions are integrated back by the original development team. +* **Medium definition**: New developers can reasonably make contributions to the software, but these contributions are integrated back by the original development team. -* **Strong Definition**: A different set of developers from the original developers can take over new feature development and bug fixes, and the original developers can go away (and the new team can do so cheaper than starting over from scratch). +* **Strong definition**: A different set of developers from the original developers can take over new feature development and bug fixes, and the original developers can go away (and the new team can do so cheaper than starting over from scratch). -The ultimate instance of the "Strong Definition" is the **Extreme Use Case for Sustainable Software**: +The ultimate instance of the "Strong Definition" is the **Extreme use case for sustainable software**: > Your project uses some external software Package X in such a way that it would be very difficult and expensive to rip it out and/or change the code to use something else. At some point, the developers of Package X go away, and no one is left in the development community to help extend or support Package X. @@ -45,26 +45,26 @@ Therefore, your project is forced to sustain software Package X for its own usag What technical properties of Package X would make it so that your project could continue to sustain (with reasonable cost and risk) your own project's usage of Package X, which includes activities like adding some new features, porting to new platforms and compilers, and fixing bugs (i.e., that may be exposed by adding new features and porting to new platforms and upgrading upstream dependencies)? -### Key Technical Properties of Sustainable Software +### Key technical properties of sustainable software -The following technical properties have been widely recognized to lead to software that less expensive to extend and maintain (and is therefore more sustainable). +The following technical properties have been widely recognized to lead to software that is less expensive to extend and maintain (and is therefore more sustainable). -**Open Source License**: +**Open source license**: Allow the user to change and use the software in any way that is needed for the success of their projects. Note that this does not always require a fully open-source license in many cases (e.g., such as with export controlled or ITAR software). The license just has to allow your project to change the source and use the software as needed for your project. -Picking a software license can be a tricky task and every open-source license is not equivalent. -For example, some open-source licenses like the GNU Public License (GPL), and its variations, can actually restrict the maintenance and usage of the software in many cases. +Selecting a software license can be a tricky task, and every open-source license is not equivalent. +For example, some open-source licenses, like the GNU Public License (GPL) and its variations, can actually restrict the maintenance and usage of the software in many cases. Software licensing can be complex and requires careful consideration.[9] **Documented history of development**: The development history of the software (which can be captured in the version-control history and linked issue trackers) can answer many questions that are important to the future of the software. What factors caused the software to be in its current state? What requirements went into the development of the software? -(Might some of those requirements and features no longer be necessary for future versions of the software, which would allow breaking some backward compatibility?) +Might some of those requirements and features no longer be necessary for future versions of the software, which would allow breaking some backward compatibility? **Clearly documented architecture and goals**: -A clear core domain model and architecture for the software has been documented (which is represented in the code or a clear documented mapping of the domain model to software)?[6] +A clear core domain model and architecture for the software has been documented (as represented in the code or a clear documented mapping of the domain model to software).[6] This document and domain model are needed to constrain the scope of the software and to continue to improve software cohesion and internal consistency with future changes. **Strong, portable, well-documented and robust tests**: @@ -77,18 +77,18 @@ Quality tests like these can take the place of a lot of documentation that one w These tests are needed to safely change or port the software and to understand the intended behavior of the software to support future usage or changes. **Clean, logical, and understandable code interfaces and implementation**: -Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, other well-known design and implementation principles.[7],[8] +Properties of clean code include self-documenting code, other minimal necessary internal and external documentation, elimination of duplication, and other well-known design and implementation principles.[7],[8] **Fast building code and fast running test suite**: An important aspect of sustainable software that is often overlooked is the computational overhead needed to build the software and tests, and to run the test suite(s). A software package that requires significant computational resources to rebuild and test the code after any change represents a huge technical debt that must be carried around by future maintainers and sponsors of the software package. Software that is very computationally expensive to build and test, or requires special hardware (like GPUs), can impose a huge burden on its sustainability in the need to procure, set up, and maintain the computing resources and DevOps infrastructure needed to utilize them. Alternatively, software that builds relatively quickly and where the tests can be run in less time can often take advantage of free cloud continuous testing services. -(For example, at the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms with relatively tight limits on the computational loads.) +(For example, at the time of this writing, services like GitHub Actions and GitLab CI provide free cloud computing cycles to test software projects on these platforms, with relatively tight limits on the computational loads.) **Well-defined and well-regulated internal and external dependencies**: Reuse and sustainability are greatly aided by minimizing external dependencies and having well-structured internal dependencies within the software package itself (established using good design and build modularity). -For example, even if your project only depends on small piece of a large external software package, if that smaller external piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software that you never use as you port to new platforms and perform other maintenance tasks. +For example, even if your project depends only on a small piece of a large external software package, if that smaller external piece cannot easily be targeted and extracted, then you may be stuck having to configure and build a large amount of software that you never use as you port to new platforms and perform other maintenance tasks. The less code you have to configure and build, the easier it is to sustain if needed. **All upstream dependencies are also sustainable software**: @@ -102,19 +102,19 @@ In addition, especially smaller or extremely well-structured software packages t (If needed, you could sustain such an upstream package yourself for your project's usage at a reasonable cost.) -### Some Key Practices for Creating and Maintaining Sustainable Software +### Some key practices for creating and maintaining sustainable software -While this article has focused on the technical properties of the software itself, there are several key practices[7],[8] that can aid in the creation and maintenance of sustainable software that possess these technical properties, including some of the following. +While this article has focused on the technical properties of the software itself, several key practices[7],[8] can aid in the creation and maintenance of sustainable software that possess these technical properties, including some of the following. -**Development and Collaboration Workflows Practices:** -* For shared development, use a distributed version control tool (e.g. Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. +**Development and collaboration workflows practices:** +* For shared development, use a distributed version control tool (e.g., Git) to manage the source and use appropriate development and integration workflows according to well-established idioms appropriate for your project. * To encourage peer contributions, use an open-source software development platform that facilitates collaborative workflows (e.g., GitHub, GitLab, BitBucket). -**Requirements Tracking Practices:** +**Requirements tracking practices:** * Every non-trivial change to the software should be driven by a clear requirement or other clearly defensible rationale. * Create well-structured and well-documented version control (i.e., Git) commits for every change to the software, describing why the change was made and point to any requirements-related documentation (e.g., issue trackers). -**Clean Understandable Coding Practices:** +**Clean understandable coding practices:** * Favor languages that are more widely known and/or well-supported. * Use domain-driven design for the key interfaces and implementation details.[5] * Strive for self-documenting code (i.e., reduce the need for extra documentation that typically does not get maintained). @@ -123,15 +123,15 @@ While this article has focused on the technical properties of the software itsel * Reduce software complexity (e.g., deeply nested control structures, deep inheritance hierarchies, etc.). * Use automatic code formatting tools (e.g., Clang-Format). * Use static analysis tools to enforce coding standards (e.g., Clang-Tidy). -* Have all changes to the code, tests, or documentation reviewed by at least on other knowledgeable developer (focusing on issues that cannot be found and enforced by automated tools like Clang-Format and Clang-Tidy). +* Have all changes to the code, tests, or documentation reviewed by at least one other knowledgeable developer (focusing on issues that cannot be found and enforced by automated tools like Clang-Format and Clang-Tidy). -**Testing Practices:** +**Testing practices:** * Favor verification and acceptance tests over no-change regression tests.[4] * Use acceptance-test driven development (ATDD) and unit-test driven development (TDD) (because these tend to lead to better tests with higher code coverage and feature coverage than tests that get created after the code is written). * Invest in making tests run as fast as possible (expensive tests are a significant form of technical debt). * Use static analyzers (e.g., Clang-Tidy) and runtime memory checkers (e.g., Clang address/memory/leak sanitizers)[3] to look for software defects. -**DevOps Practices:** +**DevOps practices:** * Use build and test systems that are better known and/or supported that can create portable builds (e.g., CMake) and run tests on all target platforms (e.g., CTest). * Make it easy to see summaries of test results and the ability to drill down into more details about what ran and what passed or failed and why (e.g., CTest and CDash). * Set up automated builds that run tests before integrating changes to the main development branch (e.g., use continuous integration frameworks that are integrated into GitHub or GitLab). @@ -139,9 +139,9 @@ While this article has focused on the technical properties of the software itsel ### Summary -Some key technical properties of a software package (and its upstream dependencies) can have major impact on reducing the cost of maintaining and extending a given software package, and therefore improving its sustainability. -In some cases, the software can be sufficiently clean, well-tested, well-structured, and well-documented, and with minimal-enough upstream dependencies, that it can be reasonably sustained by any motivated developer; even if the originating development team and/or organization disappear. -This is the extreme form of sustainable software that approaches the ideal of ***Self-Sustaining Software*** and should be the goal for many essential software packages in a software ecosystem. +Some key technical properties of a software package (and its upstream dependencies) can have a major impact on reducing the cost of maintaining and extending a given software package, and therefore improving its sustainability. +In some cases, the software can be sufficiently clean, well-tested, well-structured, and well-documented, and with minimal-enough upstream dependencies, that it can be reasonably sustained by any motivated developer, even if the originating development team and/or organization disappear. +This is the extreme form of sustainable software that approaches the ideal of ***self-sustaining software*** and should be the goal for many essential software packages in a software ecosystem. In identifying these desirable technical properties, projects can adopt and adapt development processes that help to produce and maintain these desirable technical properties. @@ -154,8 +154,8 @@ In identifying these desirable technical properties, projects can adopt and adap ### Author bio -Roscoe A. Bartlett earned his PhD in chemical engineering from Carnegie Mellon University researching numerical approaches for solving large-scale constrained optimization problems applied to chemical process engineering. -At Sandia National Laboratories and Oak Ridge National Laboratory, he continued research and development in constrained optimization, sensitivity methods, and large-scale numerical software design and integration for computational science & engineering (CSE). +Roscoe A. Bartlett earned a PhD in chemical engineering from Carnegie Mellon University, researching numerical approaches for solving large-scale constrained optimization problems applied to chemical process engineering. +At Sandia National Laboratories and Oak Ridge National Laboratory, he continued research and development in constrained optimization, sensitivity methods, and large-scale numerical software design and integration for computational science and engineering (CSE). Dr. Bartlett currently focuses on software engineering challenges in CSE as well as the development of build, test, and integration software and processes for CSE.