Improve Modular Code pattern (#475)

* Focus the problem

Generalize the problem (less contextual):
- Predisposition is more of a force than a problem.
- Modularization solves more problems in different contexts.

Detail further the effects of lack of modularization.

* Correct and expand the context

- Remove the lack of mandate because it might or not be the case.
- Remove the exclusion of legacy code. It is a clear use case.
- Making code modular doesn't take extra effort and time over the
  alternatives.
+ Include advantages for documentation

* Organize forces

* Group in pro/con/neutral
* Turn Frequent turnover into a pro
* Explain impact opportunity for newbies

* Describe resulting context

Move some points from Solutions section to Resulting Context.
They describe effects of modularization, not actions to be taken
towards it.

* Reorganize solutions

1. Describe modularization as the main solution. The rest are secondary
   actions to implement and/or support modularization as a practice.
2. Prepare (offer education) first
3. Then, decide to go for it
4. Finally take the first steps.

- Mitigating risk and fear of changes is a result, not an action.
- Providing incentives is questionable. Its benefits should suffice.
- Paralell labour moved to 'Resulting context' section already as
  it is a result, not an action. Remove duplication.

---------

Co-authored-by: Sebastian Spier <[email protected]>
Co-authored-by: Mishari Muqbil <[email protected]>

Author: 3 people

patterns/1-initial/modular-code.md

@@ -8,54 +8,70 @@ The lack of modularization in the software architecture prevents reuseability, a
 
 ## Problem
 
-Engineering does not want to spend the extra resources needed to develop modular components. This applies to managers and developers alike. As a result, fewer components end up being reused, leading to duplication of work.
+With rare exceptions, monolithinc code is difficult to contribute to as it packs much functionality (much to read, much to grasp, much to test, much to review, and much to document). Finding slots and the right mood to attack big chunks of work is difficult.
+
+The same functionality is reimplemented redundantly causing waste of unneeded re-design and re-development and duplicated mainteinance effort.
+
+Sometimes the first problem causes the second, but it might also happen spontaneously.
 
 ## Context
 
-* There is no corporate mandate for modularized code.
-* This is a new product/new code, not a legacy product/code.
+* There might be potentially reusable functionality buried in monolithic code. Legacy code tends to be less modular than new one.
 * There is an available repository for sharing code.
-* Making code modular takes extra effort and time to develop.
+* Source code can be as useful as documentation on small enough pieces.
+* Documentation needed for getting started using a small piece of code is easy to write.
 * Time commitments might already have been made for customer deliveries (not changeable).
+* The value of modularity is nearly invisible for end users.
 
 ## Forces
 
-* There is a learning curve to writing code that can be reused.
-* Extra documentation is required for reusable code.
-* Some companies have a common components group that develops reusable code, but others feel that such components should be developed by those business lines that are using the components and a library of common components could be established.
-* Developers might not know how to write modular code.
-
-* Might be a fear that if not done properly, quality might be impacted.
-* Developers might have no incentive to write modular code (due to their tight schedules and lack of a mandate).
-* If there is frequent turnover of team members, modularization may not be a priority.
-* You might be dealing with legacy systems (can't be simply refactored or rewritten).
-* Requirements might be different for writing modular code.
-* Architectural constraints might impact modularity.
-* Developers who develop monolithic code bases might lack the perspective of how modularity might improve how they work.
-* Level of communication between teams can impact ability/inclination to modularize.
+* Against:
+  * Developers who develop monolithic code bases might lack the perspective of how modularity might improve how they work.
+  * Developers might not know how to write modular code.
+  * You might be dealing with legacy systems. Might be a fear that if not done properly, quality might be impacted.
+  * Architectural constraints might impact modularity.
+  * The value of modularity is nearly invisible for end users.
+* In favor:
+  * Modularization mitigates risk and fear of quality degradation from accepting InnerSource contributions.
+  * Companies moving to use more open source code will appreciate modularity more over time.
+  * Code protected through reliable automated testing offers a chance for newcomers to safely have an impact by refactoring. Modularization is a powerful goal for refactoring. And refactoring usually drags additional benefits.
+  * Frequent turnover of team members speaks for modularization, as it helps newcomers to learn about the system at smaller bits.
+* Neutral / Two-folded:
+  * Some companies have a common components group that develops reusable code, but others feel that such components should be developed by those business lines that are using the components and a library of common components could be established.
+  * Level of communication between teams can impact ability/inclination to modularize.
 
 ## Solutions
 
-* Provide incentives to teams to invest in modular code. Modular code is far more reusable. This could work well for large teams when working on modularized projects; team members can focus on their smaller assigned tasks.
-    - Developers could get an opportunity to increase their influence in the organization.
-    - Modular code makes the pathway to open source smoother.
-    - Modular code facilitates division of labour (as required for work in larger teams, or as an open source project)
-    - Modular projects enable team members to focus on their own smaller assigned tasks.
-    - Modular code makes Agile implementation easier.
-    - Modular efforts increase autonomy and accountability for Engineers, which can raise satisfaction and quality.
-* Select certain "success projects," teams that will develop reusable code and demonstrate the long term success. This can help motivate others (they see what is possible and what is in it for them). Transparency is critical.
-* Offer education. Modular code is well-understood; there is a lot of literature in favor of this.
-* Acknowledge and drive acceptance for the cost of modularization. Build time into the release schedule for this.
-* Companies moving to use more open source code will appreciate modularity more over time.
-* Mitigate risk and fear of quality degradation from accepting InnerSource contributions.
-* Establish a checklist of elements to be checked off to classify a component as reusable.
-    - There could be requirements on tests, tools and documentation before considering a component as reusable
-    - Introduce refactoring as organic effort and strive for it to become part of the culture. Refactoring leads to more modular code and reduction of technical debt.
-* Establish standards on testing methodology, labeling of repos.
+Modular code is far more reusable. Decoupling functionality into smaller narrow-focused modules eases
+and therefore promotes external contributions and onboarding of newcomers.
+
+* Offer education.
+  * On why: Lack of modularity is technical debt. It increases costs but hides them by shifting these into the future.
+  * On how: Modular code is well-understood; there is a lot of literature in favor of this that can be used for training.
+  * Select certain "success projects", teams that have developed reusable code and can demonstrate the long term success. This can help motivate others, as they see what is possible and what is in it for them. Learning directly from other developers is critical.
+* Introduce refactoring as an organic effort and strive for it to become part of the culture.
+  * Acknowledge and drive acceptance for the investment in modularization. Build time into the release schedule for this.
+* Search for modularizable functionalities:
+  * Identify common functionalities and code blocks with potential for profitable modularity.
+  * Establish a checklist of elements to be checked off to classify a component as reusable.
+    There could be requirements on tests, tools and documentation before considering a component as reusable.
+    Establish standards on testing methodology, labeling of repos.
+* Eat the elephant in small bites. Break modularization down into baby steps, like
+  1. Find internal would-be customers. Better ask them over guessing on your own.
+  1. Define decoupling scope and preferred decoupling methods.
+  1. Develop automated testing protection.
+  1. Document usage of modules.
+  1. Introduce semantic versioning.
+  1. Use a dependency management software such as pip, nuget, npm.
+* More information and techniques are available from the book *[Working Effectively with Legacy Code](https://www.oreilly.com/library/view/working-effectively-with/0131177052/)* by Michael Feathers and *[Refactoring: Improving the Design of Existing Code](https://martinfowler.com/books/refactoring.html)* by Martin Fowler.
 
 ## Resulting Context
 
-**Pattern Idea**: Time is spent making the shared code modular so it can be reused.  
+* Modular code facilitates division of parallel labor (as required for work in larger teams, or as an open source project).
+* Modular projects enable team members to focus on their own smaller assigned tasks.
+* Modular code helps Agile: For the same functionality, you'll need to change more bits, but the modularity helps to materialize sooner (earlier and more reliable validations) and to prioritize the most relevant bits (separate value from waste).
+* Modular efforts increase autonomy and accountability for Engineers, which can raise satisfaction and quality.
+* Modular code makes the pathway to InnerSource and open source smoother.
 
 ## Known Instances
 
@@ -70,3 +86,4 @@ Initial
 * Tim Yao, Nokia
 * Erin Bank, CA Technologies
 * Keerthi Surapaneni
+* Igor Zubiaurre