Changes for page Clean Code

Last modified by chrisby on 2024/05/20 08:54

From 1.4 to 1.5 From 1.7 to 1.8

From version 1.5

edited by chrisby
on 2023/11/17 21:42

Change comment: There is no comment for this version

To version 1.7

edited by chrisby
on 2023/11/17 21:45

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,940 +1,7 @@
--# Clean Code
++Clean code is the practice of writing code that is easy to understand and maintain. Every programmer should be familiar with the principles of clean code.
--### General considerations
++### Topics
--* "The only way to go fast is to go well." To code clean, you have to code clean.
--* Refactor bad code immediately and not later because "Later equals never." (LeBlanc's Law)
--* A developer reads much more than he writes. Clean code is meant for people reading it to save their time.
--* The first draft of a concept is always dirty. The trick is to improve it step by step until it is clean. No one writes clean code off the cuff.
--* Always use English as language in your code and documentation.
--* Practice makes perfect!
++{{children/}}
--## Expressive names
--
--*
--
--Choose meaningful names.
--    *
--
--Names should be chosen as carefully as the name of his firstborn child.
--    *
--
--Implicity: It should be self-evident from reading the code how it works.
--*
--
--Choose names that are descriptive of the purpose.
--    * For example, a variables name should stand for one concept. Its better to have a variable unorderedNumbers, which is sorted and stored in orderedNumbers instead of saving both lists in the same variable numbers.
--*
--
--Avoid misinformation.
--    * For example, ambiguities, confusion with similar names or easily confused characters (l and 1, O and 0).
--*
--
--Make differences clear.
--    * Avoid very similar expressions.
--    * Blank words are redundant (a, an, the, info, data).
--* Use pronounceable names. Programming is a social activity that people talk about with others.
--*
--
--Use searchable names.
--    * The length of a name should correspond to the size of its scope. For local counting loops, one letter is enough; if the variable is used in multiple places in the code, it needs a longer name.
--*
--
--Avoid encodings.
--    * There should be no references to the scope or type of the variable in the name.
--*
--
--Avoid mental mappings.
--    * The name of a variable should not have to be mentally translated into another. Clarity has absolute priority.
--*
--
--Class names
--    * Names of classes consist of nouns or substantivistic expressions.
--*
--
--Method names
--    * They consist of a verb or an expression with a verb. Accessors, mutators, and predicates should be named after their value and follow the JavaBean standard (prefixes: get, set, is, has).
--    * Overloaded constructors can lead to confusion, e.g. if a float is to be passed once and an int once. Constructors should be declared as private and functions should be used to create instances whose names highlight the difference.
--* Avoid humorous names.
--*
--
--Choose one word per concept.
--    * "get" instead of "fetch" and "retrieve".
--* No puns.
--* Avoid ambiguities as in the word "add" (addition or adding).
--*
--
--Use names of the solution domain.
--    * Programmers will read your code, so use technical language.
--*
--
--Use names of the problem domain.
--    * If there are no terms from computer science. Then at least domain experts can refer to it.
--*
--
--Add meaningful context.
--    * Together with the names of other variables and methods, this context can be created.
--*
--
--Do not add superfluous context.
--    * Shorter names are better than longer ones, as long as they are clear. Names should be simple, but meaningful.
--* Dare to rename things. Your colleagues should be grateful for improvements.
--
--## Functions
--
--*
--
--Small!
--    * Maximum 20 lines.
--    * Blocks and indentations should also be short. Blocks within if, else, or while statements should be one line long. Presumably, a function call should be included.
--    * Indentation depths should not be greater than one or two levels.
--*
--
--Functions should do one task.
--    * They should do it well. They should do only that task.
--    * All instructions within the function should be on the same abstraction level. Sub-functions perform tasks which are one abstraction-level deeper.
--    * Sections within a function are symptoms that it performs more than one task. These function should be decomposed.
--*
--
--One abstraction level per function
--    * The Stepdown Rule: Code should be easy to read top-down: Below a function should be its sub-functions going down one level of abstraction.
--*
--
--Switch statements
--    * They are unfortunately large. Rule of thumb: they can be tolerated if they appear only once, are used to create polymorphic objects, and are used behind an inheritance relationship so that they are invisible to the rest of the system.
--* Use descriptive names.
--*
--
--Function arguments
--    * The fewer the better. Triads should be avoided. More than three arguments are forbidden. The fewer arguments a function takes, the easier it is to understand and the less error-prone it is.
--    *
--
--Common monadic functions:
--    *
--        * ask the argument a question or manipulate/convert it
--        *
--
--events: one input, no output, reader should recognize that it is about an event by the functions context and name
--
--→ Otherwise, rather not use monadic functions.
--    * Avoid flag arguments. It shows that the function performs two tasks, depending on whether the flag is true or false.
--    * Dyads should be converted to monads if possible, but cannot always be avoided. Sometimes they are also useful, e.g. when passing 2D coordinates, because the arguments are connected by a cohesion.
--    * Argument objects: If many arguments are to be passed to a function, it often makes sense to combine them as a separate concept in a new class.
--    * Verbs and keywords: Function names can form a logical combination with the arguments, such as "write(name)", or you can integrate the arguments into the function name, e.g. to avoid interchanges.
--*
--
--Avoid side effects.
--    * Functions should do only what their name says.
--    * Functions with output arguments, i.e. objects that are used as input and processed, should not be used. Instead, with a method of the object should be used to make it clear that the object itself is being processed.
--*
--
--Separate statement and query
--    * Functions should either provide information about the object or do something, but not both.
--*
--
--Exceptions are better than error codes (with if/else statements).
--    * Error.java is a dependency magnet with its enumeration of error codes and should be replaced with exceptions and derivations of the Exception class. → Easy extensibility (OCP)
--    * Extract try/catch blocks. Error processing is a task. So it deserves its own function.
--*
--
--DRY - Don't repeat yourself principle.
--    * Duplications in the code and multiple uses can usually be avoided by abstractions.
--*
--
--Structured programming
--    * Small functions may occasionally contain return, break, and continue statements. goto statements would only make sense with large statements and should therefore be avoided.
--*
--
--How do you write good functions? → Always the same principle:
--    1. Write down thoughts, restructure, etc.
--    1.
--
--Refactoring until one is satisfied and passes all tests.
--
---> TODO: Usually you write dirty code first and then refactor until its clean. Nobody write clean code out of the blue.
--* System are not programs to be written, but stories to be told. Everything must fit together.
--
--## Comments
--
--* The code should speak for itself. Comments are at best a necessary evil, if you can't express it through the code.
--*
--
--Comments can lie because they can hardly be maintained.
--    * Comments are not a substitute for bad code.
--    * Explain them in and through the code.
--
--
--### Good comments:
--
--* Legal comments: Copyrights, Authors. It's best to reference a standard license or external document so as not to deface the code.
--* Informative comments
--* Statement of intent
--* Clarifications
--* Warnings of consequences
--* TODO comments
--* Reinforcement of code that is otherwise perceived as unimportant
--* Javadocs in public API's.
--
--### Bad comments
--
--* Whispers
--* Redundant comments
--* Misleading comments
--* Prescriptive comments
--* Diary comments
--* Chatter
--* Do not use a comment if it can be replaced by a descriptive function or variable.
--* Position identifier
--* Comments after closing parentheses to emphasize sections may make sense for long functions. They should be avoided and the function abbreviated.
--* Attributions and asides are unnecessary because source control systems take over this job.
--* Commented code
--* HTML comments
--* Non-local information
--* Too much information
--* Unclear context
--* Function header
--* Javadocs in non-public API's
--
--## Formatting
--
--* Formatting is important. Its purpose is good communication with other programmers and it influences all subsequent versions of the software.
--* Team rules: Team formatting rules take precedence over personal preferences. A team of developers should agree on a uniform formatting style beforehand. You should define the style in the code formatter of your IDE.
--
--### Vertical formatting
--
--* Rule of thumb: Typically 200 lines per file. Maximum 500 lines.
--* Newspaper metaphor
--* Vertical openness between concepts: Use blank lines as separators of related code units.
--*
--
--Vertical density
--    * Lines of code that belong closely together should be close together (conceptual affinity - e.g., similar names or tasks they perform). This hardly works for related concepts in different files (like protected variables), so such constructs should be avoided. The reader should not have to search through many files to understand a concept.
--    * Variables should be declared as close as possible to where they are used. Control variables should be declared inside the loops. Instance variables should be declared at the beginning of a class. Calling functions should be placed above called functions to create a reading flow.
--*
--
--Vertical arrangement
--    * The more important the concept or the higher the level of abstraction, the further up something should be in the code; details belong at the bottom.
--
--### Horizontal formatting
--
--* Short is better. Maximum 120 characters.
--*
--
--Horizontal openness and density
--    * Whitespaces to group tasks that are closely related or separate tasks that have weaker ties to each other. For example, use whitespaces around assignment operators, between function arguments, or to make operator precedence clear.
--*
--
--Horizontal alignment
--    * Indentations are a must. Indentation rules should never be broken. You should refrain from abbreviating small if statements or while loops in a line.
--* Avoid dummy sections = code sections that do nothing and often just contain a semicolon. If you do use them, the semicolon should not be at the end of the same line, but indented on the next line.
--
--## Objects and data structures
--
--### Data Abstraction
--
--* Objects hide its data and implementation details while data structures just contain publicly accessible data. They are totally different concepts and should not be mixed.
--* The purpose of private variables is that they are not accessible from the outside. If you add getters and setters to each variable, this concept is softened.
--* Getters and setters are direct accesses to the variables. However, we often want to return abstract concepts such as averages or proportions and not work directly with this data.
--
--### Data/object anti-symmetry
--
--* Objects hide data and reveal functions to work with that data. Data structures reveal their data and have no functions.
--* Procedural code (code that uses data structures) makes it easy to add new data structures without changing the existing data structures. In contrast, OO code makes it easy to add new classes without changing existing functions. The phrase "everything is an object" is a myth.
--* Good programmers are aware of this fact and use the appropriate approach depending on the situation.
--
--### Law of Demeter
--
--* A module should not know anything about the inside of the objects it manipulates. The inside should not be revealed via accessors.
--*
--
--A method f of a class C should only call the following:
--    * other methods of C
--    * objects created by f.
--    * objects passed to f as arguments.
--    * objects contained as instance variables of C.
--*
--
--The method f should not call methods of objects returned by an allowed function. Speak to friends, not strangers.
--    * Don't use friend.getStranger().doStrangeStuff().
--    * Instead, the neighbor should provide a proper service: friend.callServiceInternallyUsingStranger()
--*
--
--Train catastrophe: train wrecks should be avoided and, if necessary, split by defining new variables as intermediate storage. E.g. don't use obj1.getObj2().getObj3().getObj4()
--    * -> Maybe for clarification, trains are okay e.g. for functional programming, but not when you walk through a lot of objects/units of your code. Coupling would be high. -> stiffness
--* Hybrids are present when classes contain public variables or public accessors/mutators for private variables and thus reveal them. This is also referred to as feature envy because these hybrids can be treated similarly to data structures. Avoid such structures. They have the disadvantages from both concepts because they make it difficult to add new features as well as new data structures.
--* Hide structure: If you know too much about an object, e.g. because you use train wrecks, you should replace them with structures that do not reveal any information about the object.
--
--### Data Transfer Objects (DTO)
--
--* Ideally, they contain only public variables and no functions.
--* There are useful structures, for example when communicating with databases or parsing messages from sockets.
--* Bean form: Its a standard where private variables have getters and setters. But they offer no advantages compared to ideal-typical DTO's. They might only appear like objects but are actually data structures.
--* Active records: public variables and navigation methods. They are often direct translations of database tables and other data sources. Avoid treating them like normal objects and don't include business rules in them, otherwise hybrids will result. Active records should be treated as data structures and business rules should be written as separate classes.
--
--## Error Handling
--
--### General Considerations
--
--* Error handling is important. But if it dominates so much that it obscures the logic behind it, it is wrong.
--*
--
--Use exceptions instead of return codes.
--    * The latter are confusing and it's easy to forget to check them by the caller.
--    * Error handling is a separate task and deserves its own function.
--*
--
--Write try-catch-finally statements first
--    * New code should be tested in such structures. If an error occurs, the program will still be executed. Afterwards, the error can be analyzed and refactoring of the code can be done.
--* Error handling should be written separately from the main code logic. This improves the maintainability of our code.
--
--### Should unchecked exceptions be used?
--
--* Checked exceptions are a violation of the OCP. Between throwing and catching the exception, the signatures of all functions must be declared to pass it on. A change to one function may require a change to all functions above it.
--* Throw exceptions with context so that you can trace the source and location. Stack traces are useful, but do not provide the purpose of the failed operation. Exception should be passed with an informative error message. The failed operation and type of failure should be mentioned. Logging should take place in the catch block.
--* By passing exceptions to higher levels of abstraction, the higher level structures know something about the lower level ones, which is a violation of Demeter's law.
--
---> TODO: A comment about error handling in Go would be interesting. Go does very often return errors, but generic error interface, not specific types. So this does not violate OCP I think but rather indicates, that an operation may fail.
--
--### Definitions
--
--*
--
--Define error classes with the caller's requirements in mind.
--    * Errors can be classified by source or type. However, attention should be paid to how exceptions are caught. → Wrapping/wrapping third-party API's is one of the best practices. This minimizes dependencies, one can easily switch API or simulate and test a third party API. One is no longer bound by the API design decisions of the vendor.
--*
--
--Define the normal flow
--    * It sometimes makes sense to replace exception handling with the special case pattern so that no errors are thrown and the program is interrupted. To do this, you create a class or configure an object to handle the special case. Instead of triggering an XXXNotFoundError, one could return a default value or an empty list in the special case. Either build an appropriate case distinction into a method or use prebuilt tools that generate an emptyList if the passed object is null.
--
--
--
--### The Null Problem
--
--*
--
--Do not return null.
--    * This can quickly overload the program with null checks. Instead, you can apply exception handling with nullExceptions or return special-case objects, although the latter is often easier to apply.
--    * A common source of errors when returning null is that checking for null is forgotten and thus checked exceptions are thrown.
--*
--
--Do not pass null.
--    * Passing null to methods is even worse. You could create your own exception type, but it has to be handled. You could use assert, but then runtime errors occur. Best to forbid passing null arguments.
--*
--
--How to handle null
--    * Work with Java's Optional class, return empty lists or default objects instead of null.
--
--## Boundaries
--
--* Boundaries are about the integration of third-party packages.
--
--### Working with third-party code:
--
--* Flexible interfaces are often useful, but due to their broad application possibilities, you can also miss the specific requirements of the programmer. For example, there might be too many access rights through methods, or the code would have to be corrected in several places when modifying such a library.
--* By embedding the library in its own class, details can be hidden and functionality reduced. This improves independence and maintainability.
--* Not every third-party library needs to be encapsulated. However, it should not carelessly be passed around the system. You should restrict it to the class or close family of classes in which it is used. It should not be used as an argument or return value when using public API's.
--
--### Explore and get to know boundaries
--
--* The point of third-party code is to save time. It's not our job to test code for functionality.
--* To get to know the API, one could read the documentation, which takes a long time. You could include the API in your program, but debugging is time-consuming and you don't know if the bug was generated by your own or third-party code.
--*
--
--Learning tests are better suited.
--    * One can write small test environments in the same way as one would integrate the third-party code into one's own software. Now one can test to check the functionality and understand it. The focus of the tests is on what we need from it.
--    * Learning tests are better than free. In addition to understanding, the tests can determine if the latest updates to the external library affect compatibility.
--
--### Miscellaneous
--
--*
--
--Use code that doesn't exist yet.
--    *
--
--If you haven't written the API yet, it makes sense to set up a desired interface for how the API should work. This will provide a clean separation. In the end, you can use an adapter to close the bridge between the desired interface and the API.
--    *
--        * Explanation of the last sentence: Once the actual API is built, there may be differences between the initially designed interface and the final implementation. An adapter is a design pattern that can be used to reconcile these differences. It allows the existing interface to be used without modifying the actual API, essentially translating calls from the interface to the API and vice versa.
--        * I am really not sure about that last sentence. Better re-read it.
--*
--
--Clean boundaries
--    * It's better to depend on something you control than something you don't. Your code should depend of wrapper classes instead of directly depending on the third-party library.
--    * Dependence on third-party code can also be avoided by referencing it in as few places as possible.
--
---> TODO: Wrap 3rd party libraries.
--
--## Unit Tests
--
--### Introduction
--
--* Every detail of the code should be meticulously checked for functionality. This means that results are checked for correctness and inner variables (even at runtime) are compared with expected values. The entire definition and value space should be tested.
--*
--
--Tests should work as well as explicitly fail for the tests to be considered passed. Positive results show that the function does what it is supposed to, negative results show that the function observes limits.
--    * own: I think it is important to handle negative results as well as the classes should handle them in a very specific manner which is part of its expected behavior as well.
--
--### Three laws of Test Driven Development (TDD)
--
--1. You must not write production code until you have written a failing unit test.
--1. The unit test must not contain more code than is required for the test to fail and compile correctly.
--1. You must write only enough production code to pass the currently failing test.
--
--* Writing a test takes about 30 seconds and is done just before writing the production code. Thus, dozens of new tests can be created per day.
--
--### Why should tests be kept clean?
--
--* When the production code is changed, the test code must also be changed. For this reason, tests should also be kept clean. Test code is just as important as production code. Unclean tests will eventually not be used and will ensure that production code gets dirty as well.
--* Unit testing ensures that code remains flexible, maintainable and clear. With testing, you're not afraid to change your code. Without tests, every change is a potential bug. The more complete the test coverage, the less the fear.
--* An automated suite of unit tests that cover production code is the best way to keep it clean.
--
--### How to keep tests clean?
--
--* Most important feature: readability. The criteria are the same as for production code: Clarity, simplicity, and density of expression.
--* Details are problematic in code if they obscure the purpose. If they are necessary at all, they should be hidden in deeper structures such as functions with catchy names.
--* Domain-specific language: Refactoring in a constantly ongoing process. During refactoring, an API develops along the way, which is useful for future tests.
--* The double standard: test code should be clean, but it does not need to be as CPU or memory efficient as production code because there are only small tasks to process.
--
--### One assert per test
--
--* This is a useful guideline that may be broken sometimes, for example, if it would generate code duplication. Stick to the code!
--* Stick to the given-when-then convention.
--* Consider using the Template Method pattern.
--* One concept per test. Then it is easier to understand what the individual test is supposed to do. If everything was thrown together, then it would be hard to assign the individual statements to the purposes.
--
--### FIRST - Rules for clean tests
--
--* Fast: So that they are executed often and regularly.
--* Independent: The failure of a test should not affect other test results.
--* Repeatable: In any environment, tests should be repeatable and work.
--* Self-validating: Tests should have a boolean output depending on whether they fail or work. Time-consuming manual validation is thus eliminated.
--* Timely: Tests should be written before production code.
--
--## Clean classes
--
--### Class structure
--
--*
--
--Order:
--    * public static constants
--    * private static variables
--    * private instance variables (there are rarely good reasons for public variables).
--    * public functions → private functions called by public functions should be placed immediately below the calling function according to the stepdown rule
--* Encapsulation: variables and utility functions should be private if possible. However, it may still happen that protected is required. However, this should only be used if there is no other way.
--
--### Classes should be small
--
--* But not too small either. Avoid god classes. The amount of responsibilities of a class are a measure whether a class is too big or not.
--* The name of a class gives information about its responsibility. If you can't find a suitable name, there are probably too many responsibilities.
--* Very general words like 'Processor', 'Manager', or 'Super' are so general that they are an indication of too many responsibilities.
--* You should be able to describe the class in 25 words without using the words "and", "or", and "but".
--* SRP - Single-Responsibility Principle: A class or module should have exactly one reason for a change and thus exactly one responsibility.
--* It is important to make the code work. This is one of the important concerns of a programmer. Often it is forgotten that the cleanliness of the code is also an important concern that must be addressed. Having many small classes is a good thing, because you know where to look without having to wade through the clutter than if you have a larger class with multiple tasks. Small classes are easier to understand.
--* Many small classes reduce the occurrence of merge conflicts.
--* It's easier to write test for small classes as less code and fewer dependencies are to be considered.
--
--### Cohesion
--
--* Cohesion between a method and a class is measured by how many class/instance variables the method manipulates.
--* The cohesion should be high. For this purpose, exactly those methods and variables are combined in a class that belong together. In a maximally cohesive class, every function uses every variable, which is neither advisable nor possible because it clashes with other principles.
--* If one wants to write many small functions, proliferation (multiplication) of instance variables can occur. It can happen that only a part of the instance variables is used by methods, thus the cohesion is low. Then it makes sense to split the class and create two or more classes with higher cohesion.
--
--### Maintaining cohesion leads to many small classes.
--
--* Decomposing large functions into smaller ones is often a good opportunity to reduce the size of the class.
--* Clean code is often longer than dirty code, but it is worth the space and effort.
--* Refactoring code can be done well step by step accompanied by unit testing.
--*
--
--Schedule changes
--    * After each change to a class, it must be retested because potentially other code has been corrupted. Clean code minimizes this risk.
--    * If private methods exist that serve only a small subset of a class (for example, is used by only a few functions), this may indicate potential for improvement, such as by creating a separate class.
--    * Open-Closed-Principle (OCP): Closed refers to the fact that one can make a change to the program and other classes can remain closed. Open means that modular extensions can be built in easily, for example by adding new classes or subclasses.
--
--### Isolate changes
--
--* There are concrete classes that contain implementations and there are abstract classes that contain concepts. When a client class depends on details, you have the problem that the details can change. Abstract classes and interfaces help to reduce the dependency by providing signatures. Use mocks with fixed behavior for unit testing.
--* Isolation makes it easier to understand all elements of a program. Consider the Dependency Inversion Principle (DIP): Classes of abstractions should not depend on concrete details.
--
--## System
--
--* As in the construction of a city, the construction planning/concepts should be strictly separated from the departments/details. There are different, clearly delineated responsibilities in the development team.
--
--### Separate construction and application of a system
--
--* Software systems should separate the startup process, when application objects are constructed and dependencies are "wired," from the runtime logic that takes control after startup.
--* The startup process is a Concern (concern, responsibility). The separation of Concerns is one of the oldest and most important design techniques.
--* The mixing of startup process and runtime logic is called lazy initialization/evaluation and should be avoided.
--* Separation in main: This is a possible solution approach. Main starts a builder that initiates the configuration objects. Independently of this, the application (runtime environment) to which the objects are passed is started in main.
--* Factories: Applications themselves should not create objects, because this undermines a separation of runtime and startup as well as represents a second responsibility. Therefore, you can set up factories from which an object can be requested.
--* Even better is a Dependency Injection (DI), with which an Inversion of Control can be achieved. Here, the main routine or a special container for it creates an object, which is passed to the application. In JNDI lookups, the application asks a directory server for an object and receives it in return. True DI directly allocates all resources to the application, so that the application remains passive and does not need to request anything. This is often done via setter or constructors injection. For example the Spring Framework takes care of these tasks.
--* Lazy initialization is an optimization technique that makes sense, but is often used too early. Its advantage is that objects are created only when they are needed. Many containers provide mechanisms that can be used for this.
--
--### Upscaling
--
--* Systems are never built right the first time, but are constantly expanded using incremental and iterative agility. Since you don't know what the future holds, you should focus on the concerns that are important today and implement them. Systems in software development must constantly be subjected to refactoring, but only when it is necessary.
--* Software systems do not require advance planning of the system architecture, provided that the concerns are separated from each other.
--* DBMS: Database management system for storing all objects so that they do not have to be stored in flat files.
--
--### Cross cutting concerns and aspects
--
--* Cross-cutting Concerns: These are problems that are built into many objects in the system, but cannot be combined into one module. The solution is Aspect-oriented programming.
--*
--
--Java proxies
--    * Disadvantages: Too extensive and too complicated. In addition, no system-wide, interesting execution points can be defined. They are not recommended.
--*
--
--Pure Java AOP frameworks
--    * Examples: Spring AOP
--    * POJO's = Plain Old Java Objects → are focused exclusively on their domain.
--    * Principle: Convention over Configuration, KISS, DRY.
--    * Advantage: Simple and accordingly quick to learn. It is integrated into Java and is sufficient in most cases to implement AOP.
--*
--
--AspectJ
--    * This tool has the largest range of AOP functions, but you have to learn a lot of new things. On your way to becoming a wise programmer, you should learn it, because it is worth the effort.
--
--### Test the system architectures.
--
--* Big Design Up Front (BGUF) is to be avoided. It is important, from the beginning, to separate all Concerns and thus gradually create small, well-testable modules. If difficulties arise, then you have to restructure later. However, this cannot be foreseen from the beginning, let alone planned.
--* You start with a naively simple, but nicely decoupled architecture that meets current requirements and work your stories (current concerns) into it. As the size grows, so does the infrastructure. Of course, you should still approach the project with goals and means of control. There are plans and general scopes to consider. As long as the components are decoupled, restructuring can be done well.
--* Summary: An optimal system architecture consists of modularized Concern domains, each implemented with POJO's. The different domains are integrated by minimally invasive aspects or aspect-like tools. This architecture, like the code, can be developed in a test-driven manner.
--
--### Optimize decision making
--
--* In sufficiently large systems, one person alone can't make all decisions and must relinquish decision-making power. The decision should be made by the most qualified person.
--* It is often forgotten that decisions should be postponed until the last possible point because then has the best level of knowledge for a decision. Keep options open.
--* The agility offered by a POJO system with modularized concerns enables us to make optimal just-in-time decisions based on the current state of knowledge. The complexity of these decisions is also reduced.
--
--### Miscellaneous
--
--*
--
--Apply standards wisely when they add value.
--    * Standards make it easier to reuse ideas and components, recruit developers with relevant experience, encapsulate good ideas, and link components. But the process of creating standards can sometimes take too long for the industry to wait; and some standards lose touch with the real needs of the target audience.
--*
--
--Systems need domain-specific languages
--    * Domain-Specific Languages (DSL) allow all levels of abstraction and all domains of the application to be expressed as POJO's, from the abstractly formulated policy to the concrete details.
--*
--
--Summary
--    * An invasive architecture overwhelms domain logic and degrades agility. Therefore, aspect-oriented solutions should be used for the domains for which POJO's cannot be applied.
--    * Use the simplest, working solution!
--
--## Emergence
--
--### Clean software through emergent design
--
--*
--
--Simple Design by Kent Beck - Four rules for simple design, starting with the most important rule:
--    1. It passes all tests.
--    1. It contains no duplication.
--    1. It embodies the intent of the programmers.
--    1. It minimizes the number of classes and methods.
--*
--
--Simple design rule 1: Pass all tests.
--    * If something is not testable, it is not verifiable and probably should not be used.
--    * Tests are easier to perform if there are small modules with a clear purpose (SRP). Couplings should be avoided. The more test you write, the more you try to minimize coupling and apply principles like DIP and techniques like DI, interfaces, and abstractions more often. Therefore, systems should be tested continuously during their evolution. This automatically leads to weak coupling in stronger cohesion.
--*
--
--Simple Design Rules 2-4: Refactoring
--    * The fact that we have tests takes away the fear that we might break the code by cleaning it up.
--    * Apply virtually everything we've learned so far in this document.
--
--### No duplication
--
--* Duplication leads to extra work, extra risks and unnecessary complexity.
--* Duplication does not have to mean just having the same functionalities or similar implementations. For example, two methods that provide information about an object (such as size() and isEmpty()) could be combined into one if block, their implementations linked together instead of being implemented separately. For example isEmpty() {return size() == 0;}
--* Reuse in miniature: When methods are abstracted and separated, you may notice that you can use that method in other areas. This greatly reduces the complexity of the system.
--
--### Expressiveness
--
--* It's easy to write and understand messy code because you've spent a long time thinking your way into it. But the amount of time it takes for others to get in and understand is comparatively huge, as the code is also sifted through many times. Therefore, clean code is necessary to save other people time and effort. Besides, most programmers can barely decipher their dirty code themselves after a few weeks which also costs time.
--* The main costs of a software project are caused by long-term maintenance.
--* The clearer an author presents the intention of his code, the less time others have to spend on understanding it.
--* One can lend expressiveness to one's code if, for example, one is guided by known design patterns and their naming or other standard nomenclature. Similarly, tests should convey what a class under test is about.
--* The most important way to write clean code is to try it out. Just because the code works, one should not move on to the next task. You should take time to simplify it and make it more readable. If you get stuck, you're probably done. Diligence is a valuable resource.
--
--### Minimal classes and methods
--
--* One should not overdo it when decomposing classes and methods. That's why you should create as few of them as possible, but as many to write clean code and satisfy the other principles. Since this is the least important rule, the other three rules take precedence. It should just not be seen dogmatically, to be followed blindly, but seen pragmatically in the context of the other rules and principles. Besides, that would unnecessarily weaken cohesion.
--
--## Concurrency
--
--* Objects are abstractions of processing, threads are abstractions of timing.
--
--### Why concurrency?
--
--* Concurrency is a decoupling strategy. The what is decoupled from the when. Concurrency is important and can improve the throughput and structure of an application. On the other hand, it is hard to write clean concurrent code and it is harder to debug.
--* Concurrency doesn't always improve performance behavior and but it always changes the design of the program. When working with containers, you should know exactly what you are doing.
--* Concurrency demands a certain amount of management effort, which degrades performance behavior and requires additional code. Proper concurrency is complex, even for simple problems. Concurrency bugs are usually not reproducible; therefore, they are often written off as one-time occurrences (cosmic rays, glitches, etc.) rather than treated as true defects, as they should be. Concurrency requires a fundamental change in design strategy.
--* Challenges: When threads access out-of-sync data, incorrect results may be returned.
--
--### Principles of defensive concurrency programming
--
--*
--
--SRP
--    * Changes to concurrent code should not be mixed with changes to the rest of the code. So you should separate the two cleanly.
--    * Concurrency has its own life cycle with development, modification, and polish.
--    * Concurrent code is associated with special problems that have a different form and often a higher degree of difficulty than non-concurrent code.
--*
--
--Constrain the range of validity of data
--    * Take data encapsulation to heart; restrict access to all shared resources.
--    * So you should keep the mass of shared code low, and shared resources should only be claimed by threads that need them. That means one should divide the blocks and resources into smaller blocks if necessary.
--*
--
--Work with copies of the data
--    *
--
--One can sometimes get around data sharing by:
--    *
--        * working with copies of objects and treating them as read-only objects.
--        * making multiple copies of an object, having multiple threads compute results on it, and merging those results into a single thread.
--    * It is often worth creating multiple objects to avoid concurrency issues.
--*
--
--Threads should be as independent of each other as possible.
--    * Threads should not share data or know anything about each other. Instead, they should prefer to work with their own local variables.
--    * Try to decompose data into independent subsets that can be processed by independent threads, possibly in different processes.
--
--### Things to learn before working with concurrency
--
--*
--
--Get to know your library
--    * Use the thread-safe collections provided.
--    * Use the executor framework to execute disjointed tasks.
--    * Use non-blocking solutions if possible.
--    * Multiple library classes are not thread-safe.
--*
--
--Thread-safe collections
--    * So you should use ConcurrentHashMap instead of HashMap.
--    * Author's recommendations: java.util.concurrent, java.util.concurrent.atomic, java.util.concurrent.locks.
--*
--
--Get to know execution models
--    *
--
--Basic definitions
--    *
--        * Bound Resources
--        * Mutual Exclusion
--        * Starvation
--        * Deadlock
--        * Livelock
--        * Thread Pools
--        * Runnable
--        * Callable
--        * Future
--        * Java Executor Framework
--    * Producer-consumer
--    * Reader-recorder
--    * Philosopher problem → Study algorithms and their application in solutions.
--
--### Watch out for dependencies between synchronized methods
--
--* Dependencies between synchronized methods in concurrent code cause subtle bugs.
--*
--
--Avoid applying more than one method to a shared object. If this is not possible, you have three options:
--    * Client-based locking: the client should lock the server before the first method is called and ensure that the lock includes the code that calls the last method.
--    * Server-based locking: Create a method in the server that locks the server, calls all methods, and then unlocks the server. Have the client call the new method.
--    * Adapted Server: Create an intermediate component that performs the lock. This is a variant of server-based locking if the original server cannot be changed.
--*
--
--Keep synchronized sections small.
--    * Locks are expensive because they add administrative overhead to delays. On the other hand, critical sections must be protected.
--    * Critical sections, are parts of the code that are only executed correctly if several threads do not access it at the same time.
--    * Keep synchronized sections as small as possible.
--
--### Writing correct shutdown code is difficult
--
--*
--
--You should think about a shutdown as early as possible and get it running as soon as possible. If you wait, it will always take longer. Study the available algorithms because this task is probably harder than you think.
--    * TODO: Why do I need shutdown code?
--
--## Case studies
--
--* Deep changes in the code can often destroy its functionality. The better way would be to make small changes step by step and to ensure the correct functionality of the module by testing after each change. That is the spirit of TDD: A system must be executable at all times. I must not maintain any changes that destroy the functionality of the code.
--* It can happen more often during refactoring that you insert things and remove them again shortly after.
--* Programmers who are satisfied with code that just works are behaving unprofessionally.
--* Nothing burdens a software project in the long run as much as bad code, because it rots away and its damage gets bigger and bigger. That's why you should get to work on it as soon as possible and clean it up.
--* Pathfinder rule: "Try to leave the code a little better than you found it." Code requires maintenance over time.
--* Professional review: It's not about badmouthing the other person, portraying yourself as better or denying their competence. It's about writing clean, simple, easy-to-understand code. And since nobody is perfect, everyone should accept constructive criticism from other programmers. Only from such criticisms can we learn. It's commendable and putting your code out there publicly for other programmers' peer review, after all, you're very likely to be criticized based on your mistakes. But a professional programmer knows that this is a good way to produce good code and that is the most important thing.
--
--## Smells and heuristics
--
--* Book recommendation: Refactoring by Martin Fowler
--
--### Comments
--
--* Inappropriate information: Comments should have technical annotations. Meta-data and change histories do not belong in source code.
--* Outdated comments: It is best not to write comments that can become outdated.
--* Redundant comments
--* Poorly written comments
--* Commented code → Delete!
--
--### Environment
--
--* The build process and testing should each be executed with a simple command or take place by pressing a button in the IDE.
--
--### Functions
--
--* The fewer arguments, the better.
--* Don't return argument objects. Instead, you should edit the state of an instance with methods.
--* Flag arguments are often a clear indication that the function performs two tasks and should therefore be eliminated.
--* Only one task per function.
--* Dead methods
--
--### Principles
--
--* As few languages as possible should be used in a source file.
--*
--
--Principle of least surprise:
--    * A class should implement those behaviors that a programmer may reasonably expect from it.
--    * Functions should not have unexpected side effects, but should be able to infer such things from the context of the method name. Tasks should be done consistently in the same way. E.g. naming variables according to the same system. One should choose one's conventions carefully and apply them conscientiously.
--    * Code should be inserted where the reader would intuitively expect it. Sometimes programmers choose wrong responsibilities for specific tasks.
--* DRY: Don't Repeat Yourself. No Duplications. Any violation is a missed opportunity for abstraction. switch/case or if/else structures with the same condition should be abstracted. Polymorphism can be used here. Template methods and strategy patterns can be used for the same algorithms with different lines of code. Design patterns and the OOP are often specially designed to avoid code duplication.
--* Base classes should not depend on derived classes. The concepts of base classes should be independent of those of derived classes. I.e. in a base class one should not find the name of a derived class. Of course there are also exceptions. However, base classes and derived classes should be delivered in different jars. They should not know anything about each other. ◦ Not too much information. Interfaces with many functions cause strong coupling and you may have to implement functions you don't need. So instead you should provide small interfaces with scarce functionality. The fewer methods a class has, the fewer variables it knows and the fewer instance variables a class has, the better.
--*
--
--Delete dead code. Code is dead when it is no longer executed.
--    * Where can you find dead code? In if/switch-case statements with impossible conditions, in catch statements where there is no throws in the try, or in utility methods that are never called.
--* Throw out junk: Empty default constructors, meaningless artifacts, information-less comments, functions that are never called.
--
--### Conventions
--
--* Fuses should not be turned off. So don't disable compiler warnings and tests and change serialVersionUID only as a last resort with utmost caution.
--* Define conventions. In most cases, this can be deduced from previously existing code. It does not matter where brackets are and to oppose such otherwise irrelevant specifications is childish. You can standardize your IDE formatter accordingly.
--* Magic numbers should be hidden behind constants. Strings are also meant by this. The only exception is when the meaning of a number is clear from the context of the code. For example, hours = second/3600 is acceptable. The 3600 does not have to be hidden behind a constant here. Also, constants should be used for long numerical values like Pi, so that other programmers don't have to write so many numbers, which also avoids typing errors. In all other cases, constants are appropriate because it becomes much more readable.
--* No arbitrariness: Every structure has its place, namely where it is needed and used. By convention, for example, a public class that is not an auxiliary class for another class should be at the top package level.
--
--### Variables
--
--* Vertical separation: Local variables should be defined immediately above their first place of use. Private functions should be defined below their first use. Code should be read fluently from top to bottom.
--* Hidden intentions: Run-on expressions (i.e. long expressions that could be broken into several smaller ones), Hungarian notation (i.e. including the type of a variable in its name), and magic numbers should not be used.
--* Use meaningful variables: In calculations, intermediate results should be stored in variables with meaningful names to make the code more readable. It is hard to overdo this method.
--* Encapsulate boundary conditions: If a boundary condition occurs more than once and is a compound expression (e.g. x + 1), then it is better if it is encapsulated in a new variable.
--
--### Functions
--
--* Function envy is when a method uses on accessors and mutators to manipulate the data within an object. It wishes to be part of the object so that it can access the data directly. One class accesses the internals of another class, so it should be avoided if possible. However, when weighed against other principles, it may be a necessary evil.
--* Selector functions are functions that make decisions and therefore contain, for example, a Boolean as an argument, the contents of which determine their behavior. Selector arguments should be avoided and the functions should be divided into smaller functions.
--* Methods falsely declared as static: In general, methods should rather not be declared as static. If one declares static methods, one should make sure that no polymorphism occurs and that all necessary data is given by the arguments. If you could declare a method both static and non-static, you should choose the latter. → Explanation: Static functions are not inherited. So if polymorphism should be used, i.e. inheritance and overwriting of methods should be used, this can only be done via non-static methods. How should that be possible? I call the class explicitly and not any object.
--* Function name should express action. If you need to take the documentation at hand to understand the action, then you should change the name.
--* Understand the algorithm: One should not just write down the code and change it until it somehow passes all tests. You should be sure that you fully understand the algorithm and know that it will do the job. I.e. after the code is made to work, one should refactor it until it is clean, expressive and understandable.
--* Encapsulate conditions: Boolean logic in particular is difficult to read. Therefore, one should decompose such constructs and encapsulate a new function. And avoid negative conditions. Positive conditions are easier to understand than single or even double negation.
--* Go only one abstraction level deeper in functions. This is one of the most important functions of refactoring.
--* Temporal coupling should not be hidden. You can counteract this by forcing the code into a certain order by making each step depend on the previous one. E.g. each function produces a result on which the following function depends → bucket brigade. Another programmer can read from the logic of the program that only this order makes sense.
--
--### Classes
--
--* Coding at the wrong level of abstraction. Concrete implementations should be where they are used and not an abstraction level higher. Higher level concepts belong in the higher abstraction levels. Functionality should be passed only to the classes that use it. Otherwise, the functionality must be built into a lower level.
--* Locate configurable data high. I.e. it should be in a high abstraction level and not buried in any lower function. Thus, they should be kept easily modifiable from above and can be passed down to a more concrete class as an argument if needed.
--
--### Miscellaneous
--
--*
--
--Avoid artificial coupling: General enums should not be included in special classes. Otherwise, other modules must establish a coupling to this special class only because of this, although the rest is uninteresting. The enum should get its own module and be included where it is needed. Artificial coupling = coupling of modules that serves no direct purpose.
--    * -> I think this is also why one should not use entities as DTO's but rather create separate DTO's.
--* Be precise: Consider not only, but also all possible side effects (rounding errors, null, locking mechanism for updates, non-optimal type, duplications, ambiguities due to multiple results, etc.). Avoid ambiguities or inaccuracies.
--* Structure is more important than convention. Structures that enforce conformance are better than naming conventions.
--* Don't rely on your intuition about correct functionality. Test all special cases, limits, idiosyncrasies, and borderline cases.
--
--### Convert logical dependencies into physical ones
--
--* Brief explanation: physical design concerns the arrangement of modules in the folder/package hierarchy, that is, how files are physically arranged in the project. All other relationships such as calls, imports, interfaces, inheritance are logical structuring.
--* In the book this is explained in such a way: If a higher class knows a detail, which belongs actually into a lower class, this is a logical dependence. Because on the one hand the information should not be there at all, on the other hand this is an assumption which leads to errors if the lower class does not support this dependency completely (e.g. if the lower class works only up to the value 20, but the logical dependency is just 30). The conflict can be solved by writing the dependency physically to the lower class and giving the higher class access via a method. The lower class no longer depends on the detail of the higher class, but on an internal variable.
--
--### Java
--
--* Avoid long import lists by using placeholders. This reduces the coupling. The only drawback is when two classes have the same name, but this rarely happens. This could also be an indication for a bad choice of names. That's why you should find better, different names.
--* Constants should not be inherited via interfaces if this circumvents the rules for scopes. In such a case, they should be made available via static import.
--* Use enums instead of public static final ints.
--
--### Naming
--
--* Descriptive names. Meanings of classes, variables, functions, etc. may change as software evolves, so names should be adjusted.
--* Names should correspond to the abstraction level and should not say anything about the implementation. For example, in an interface, a method should be chosen to be just as general or specific as the rest of the methods.
--* If possible, use the standard nomenclature. E.g. when using the Decorator pattern, one should use Decorator in the name. There are many conventions. Others would be: toString(), isValid(), etc. Teams specify a Ubiquitous Language at the beginning of a project. This also makes it easier for the reader if the same conventions are always used in the project.
--* Choose unique names. Clarity can be justified even if the name is long for it.
--* Names should describe side effects. Even if the name becomes long, this behavior should be recognizable.
--
--### Tests
--
--*
--
--What is the right amount of tests?
--    * A test suite should test everything that could go wrong in some way. As long as there are conditions that are not checked by the test or calculations that are not validated, the tests are insufficient.
--* Use a 'code coverage' tool. IntelliJ provides such a tool.
--* When ignored tests show ambiguity that means that behavior details are unclear because requirement details are unclear. This indicates that requirements still need to be clarified. Use @Ignore and possibly add a comment.
--* Test boundary conditions. The limits of the input and output values must be checked.
--* In case of bugs, test the neighborhood thoroughly. After finding the bug, you should test the function thoroughly. Often bugs are not alone.
--* Use the pattern of failure to diagnose. Sometimes you can see patterns that occur when tests fail. For example negative arguments cause all tests to crash. So take a step back and look at the big picture.
--* You might get clues examining the coverage patterns.
--* Tests should be fast. If they were slow, they would not be executed, especially if time is short.
--
--## Annex: Concurrency
--
--* When I/O is the bottleneck of your application, more threads will increase the performance in opposite to when CPU is the bottleneck.
--* Stress Testing: Checking the throughput of an application by sending a huge amount of requests and examining the response times.
--* Isolate concurrent code by putting it in a few separate classes.
--* Always consider the concept of execution paths: The amount of possible interleaving of instructions that are processed by at least two threads. For example, objects with mutable states could unintentionally cause different results doing the same operation twice.
--* Atomic operation = operation which can not be interrupted by other threads. But for unsynchronized processes threads can put instructions between two atomic operations.
--* synchronized prevents unintended side-effects.
--*
--
--Server-based locking is preferred over client-based locking.
--    * Server-based locking: The class used takes care of internal locking, so the user has nothing else to worry about.
--    * Client-based locking: User has to manually implement locking. This approach error prone and hard to maintain.
--* If there is no access to the server an adapter class can be used instead. Even better would be thread-save collections using extended interfaces.
--* As little synchronized code (synchronized) as possible should be used. And if, then only for small, critical code sections.
--
--### Prevent Deadlocks
--
--* Do this by making one of its four conditions impossible.
--
--### Mutual Exclusion (Mutex)
--
--*
--
--Description:
--    * When resources can't be used by mutual thread and
--    * there are less resources than threads.
--*
--
--Solutions:
--    * Use concurrently accessible resources like AtomicInteger.
--    * Increase the number of resources until its greater or equal to the number of competing threads.
--    * Check if every required resource is accessible before the task starts.
--
--### Lock & Wait
--
--*
--
--Description:
--    * Once a thread acquires a resource, it will not release the resource until it has acquired all of the other resources it requires and has completed its work.
--*
--
--Solutions:
--    * Before reservation of a resource, check its accessibility.
--    * If a resource is not accessible, release every resource and start from anew.
--*
--
--Dangers:
--    * Starvation: A thread never achieves to reserve all required resources.
--    *
--
--Livelock: Thread gets tangled up.
--
--→ This approach is always applicable but inefficient as it causes a bad performance.
--
--### No preemption
--
--*
--
--Description:
--    * A thread is unable to steal a resources reserved by another thread.
--*
--
--Solution:
--    * A thread is allowed to ask another thread to release all of its resources (including the required one) and starting from anew. This approach is similar to the 'Lock & Wait' solution but has a better performance.
--
--### Circular Waiting / Deadly Embrace
--
--*
--
--Description:
--    * When two or more threads require a resource which is already reserved by another of these threads.
--    *
--
--Example:
--    *
--        * Thread T1 has resource R1 and waits for R2 to be released.
--        * Thread T2 has resource R2 and waits for R1 to be released.
--*
--
--Solution:
--    * All threads reserve all resources in a the same order.
--*
--
--Problems:
--    * The order of reservation doesn't necessarily have to be the same as the order of usage. This leads to inefficiencies like reserving a resource at the beginning which is just required at the end of the task.
--    * Unnecessarily long locked resources.
--    * Order can not always be specified.
--
--### Problems of testing multi-threaded methods
--
--* Very tricky which is why concurrency should be avoided in the first place.
--* In general this requires a lot of iteration which makes it resource intensive.
--* The outcome is architecture dependent (OS, hardware) which introduced randomness and make the error detection unreliable.
--
--### Solution approaches for testing multi-threaded methods
--
--*
--
--Monte-Carlo-Tests
--    * Write flexible, adaptive tests.
--    * Repeatedly run them on a test server and randomly vary the test settings.
--    * If something fails, the code is defect and the applied settings should be logged.
--    * Do this early to gain tests ASAP for your testing repertoire or CI-server.
--*
--
--Execute these tests on every platform over a long time to increase the probability that
--    * the production code is correct or
--    * the test code is bad.
--* Execute the tests on a computer using simulations of application loads when possible.
--* There are tools to test thread-based code like ConTest.
--
--## Personal Additions
--
--* Readability is the most important virtue. For example, duplication is okay if its the only way to give readability.
--* Expanding Entropy: Code built upon dirty code will overtake some of its dirt and make it more stable which raises the cost of cleaning it up. Therefore, clean code up ASAP.
--*
--
--Principle of least knowledge:
--    * Are there API's providing more functionality than is actually required?
--    * Are data exposed to objects which don't require them at all?
--* Source code of other projects should not be introduced to your own project/git history. Use references like in a pom.xml (libraries, webjars), npm build files..Don't download and introduce code manually.
--* Inform about modern API's. For example Java Dates -> DateTime and File -> Files/Path, Java Modules. Also before making the decision to use a specific tool, just make some research about pro/cons and alternative solutions which might fit better to your needs..
--* Now can clean code out-of-the-box. Just begin with dirty code, and refactor as often as you need to have clean code in the end.
--*
--
--How to judge if third-party libraries are useful or not? Be pragmatical and consider advantages and disadvantages:
--    *
--
--Pro:
--    *
--        * Time reduction because it is already implemented.
--        * For well established libraries there are no costs of maintenance for the library itself.
--    *
--
--Contra:
--    *
--        * No control over the library code/service.
--        * Might not fit the projects needs or change over the time.
--        * Time is required to learn to handle it.
--*
--
--Good API's minimize costs to apply them.
--    * Easy understandable API.
--    * Only required functionalities are provided, minimal API. Maybe have a core API and use extensions/modules so that there is not that much functionality at the beginning. By working with it, users can get it step by step.
--    * Good documentation, guides, tutorials.
--    * Default configuration so that immediately results can be produced before going through big amounts of configuration.
--
--## Material
--
--* [Interesting article](https://research.swtch.com/deps) about dependencies. Solution: Create custom interface and thin wrapper between your application and the third party library.
--
--