content/blog/complexity.md

@@ -8,7 +8,7 @@ desc: What is complexity as it relates to software?
 The most [relevant definition of complexity](https://www.lexico.com/en/definition/complex) for this blog post is: (adj) "Not easy to analyze or understand; complicated or intricate." Intuition of complexity is important if you are designing, writing, or reading software.  If you are purchasing software, it is important to prioritize simpler options; it will be cheaper in the long run.  In this blog post, I will discuss identifying complexity, why it's bad, why simple is good, and how software engineers manage complexity.
 
 ## Identifying Complexity
-Before being able to manage complexity, it must be identified.  In addition to the definition, it is helpful to know indicators and examples.  Seasoned engineers sometimes call these smells; complexity is not black and white, but more of an intuition.  Some things that appear simple now may become complex in the future.
+Before being able to manage complexity, it must be identified.  In addition to the definition, it is helpful to know indicators and examples.  Seasoned engineers sometimes call these smells; complexity is not black and white, but more of an intuition.  Things that appear simple now may become complex in the future.
 
 #### Indicators
 
@@ -31,7 +31,7 @@ All software is complex; it is one of the most complex man-made things.  Physica
 
 While some complexity is unavoidable, it is best minimized.  Here are a few reasons to minimize the complexity of software:
 
-* Expensive changes: As software gets more complex, the cost to change increases exponentially.  A module bound to several business concerns is more expensive than a module that does one thing.  Engineers, business representatives, and managers need to work together instead of just handing a simple task to an engineer.
+* Expensive changes: As software gets more complex, the cost to change increases exponentially.  A module bound to several business concerns is more expensive than a module that does one thing.  Engineers, business representatives, and managers need to work together on multi-purpose modules instead of handing a simple task to an engineer to work on a single-purpose module.
 
 * Time: While money can be acquired, time is scarce.  If a project becomes expensive, some larger companies can handle it.  If the software is complex enough, the bottleneck becomes time, at which point it is too late.  Cars travel quickly on highways, partly due to their straight path (simple).  If the only way to get from A to B is a winding mountain road (complex), more time will be needed than the highway, no matter how fast a car you buy.
 
@@ -40,18 +40,20 @@ While some complexity is unavoidable, it is best minimized.  Here are a few reas
 ## Simple is Difficult, but Effective
 An antonym of complexity is [simplicity](https://www.thesaurus.com/browse/complexity). Although it is easy to explain a [simple system](https://simplesystems.tech/blog/post/simplicity), it is not easy to create one.  This is the classic investment mindset applied to time.  It is better to think twice and code once.  Here are a few examples of simplifying principles:
 
-* Encapsulation: This is a very powerful idea, especially when some complexity cannot be mitigated -- it can still be encapsulated. The inner workings of an automatic transmission are quite complex, but it is encapsulated so well that the driver simply selects "D".  As [Rob Pike](https://twitter.com/rob_pike) points out in this [video](https://www.youtube.com/watch?v=rFejpH_tAHM&t=789), the simplest interface is no interface at all; garbage collection is completely encapsulated.
+* Encapsulation: When the complexity of software cannot be mitigated, it can still be encapsulated.  This powerful idea is what enables the internet to work smoothly; each packet of information sent across it is an envelope.  The inner workings of an automatic transmission are quite complex, but it is encapsulated so well that the driver simply selects "D".  As [Rob Pike](https://twitter.com/rob_pike) points out in this [video](https://www.youtube.com/watch?v=rFejpH_tAHM&t=789), the simplest interface is no interface at all; garbage collection is completely encapsulated.
 
 * UNIX philosophy:  "Make each program do one thing well."  This can save software from becoming an indomitable mess.  Constantly adding features to the same system will eventually make it collapse in on itself.
 
-* Composition: Software should be composed of interchangeable modules.  The boundaries between modules must be well-defined.  Chess software should have 2 players, but those players do not need to be humans on a computer.  By keeping the player module separate, it can be swapped for an AI player module.  This enables better testing and more interesting games.
+* Composition: Software should be composed of interchangeable modules.  The boundaries between modules must be well-defined.  Chess software should have two players, but those players do not need to be humans on a computer.  By keeping the player module separate, it can be swapped for an AI player module.  This enables better testing and more interesting games.
 
-Removing complexity requires both science and art.  These principles are not straightforward to incorporate into an engineering process.  Once a system becomes simple, the benefits become evident quickly.  One important benefit for teams to think about is the number of engineers who can work on a project.  If a system becomes a convoluted mess, usually only a couple people can work on it.  A system designed well, especially using modularity, will increase the number of engineers who can work on it.
+Removing complexity requires both science and art.  These principles which bring about simplicity are not straightforward to incorporate into an engineering process.  Once a system becomes simple, the benefits become evident quickly.  One important benefit for teams to think about is the number of engineers who can work on a project.  If a system is a convoluted mess, usually only a couple people can work on it.  A simple system can be worked on concurrently by more engineers, making it a much more effective piece of software.
 
 ## Software Engineers Manage Complexity
-A programmer understands software languages and can program a computer to accomplish tasks.  A software engineer will do the same, with the addition of minimizing the program's complexity. In fact the act of minimizing the complexity takes up most of the engineer's time.  Many other tasks such as designing, testing, documenting, refactoring, and reviewing code are much more time intensive -- and important -- than the actual programming.
+A programmer understands software languages and can use them to have a computer accomplish tasks.  A software engineer will do the same, with the addition of minimizing the program's complexity. In fact the act of minimizing complexity takes up most of an engineer's time.  Many other tasks such as designing, testing, documenting, refactoring, and reviewing code are much more time intensive -- and important -- than the actual programming.
 
-Software engineers must create programs that are simple enough to be understood by other engineers.  This enables others to work on the project and create something greater than the sum of the engineers' abilities.  Creating obvious software is a skill acquired through working with others.  One of the most useful abilities of that skill is to use [design patterns](https://en.wikipedia.org/wiki/Software_design_pattern).  When the writer and reader of a program know a common design pattern, they can quickly communicate its intent.
+Software engineers must create programs that are simple enough to be understood by other engineers.  This enables others to work on the project and create something greater than the sum of the engineers' abilities.  Creating obvious software is a skill acquired through working with others.  One of the more useful abilities of that skill is to use [design patterns](https://en.wikipedia.org/wiki/Software_design_pattern).  When the writer and reader of a program know a common design pattern, they can quickly communicate its intent.
+
+Documentation is important no matter how simple the code.  Programs always appear simpler to their author than the reader.  This skill is necessary to work on teams that are spread across time zones.  Delays due to misunderstanding undocumented code can be costly.  Documentation manages the complexity of software by writing in clear terms what the code will do. 
 
 ## Conclusion
-Writing software is easy, but writing good software is not.  Seek simplicity to save the business and other engineers time and money.
+Writing software is easy, but writing good software is not.  Seek simplicity to save the business and other engineers time and money.  Engineers should hone their complexity-reducing skills to write better software.