depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { }
```
Better would be:
```java
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { }
```
### Position Markers
Comments like these are noising.
```java
// Actions //////////////////////////////////
```
### Closing Brace Comments
Example:
```java
public class wc {
public static void main(String[] args) {
BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
String line;
int lineCount = 0;
int charCount = 0;
int wordCount = 0;
try {
while ((line = in.readLine()) != null) {
lineCount++;
charCount += line.length();
String words[] = line.split("\\W");
wordCount += words.length;
} //while
System.out.println("wordCount = " + wordCount);
System.out.println("lineCount = " + lineCount);
System.out.println("charCount = " + charCount);
} // try
catch (IOException e) {
System.err.println("Error:" + e.getMessage());
} //catch
} //main
```
You could break the code in small functions instead of using these comments.
### Attributions and Bylines
Example:
`/* Added by Rick */`
The version control system can manage this information.
### Commented-Out Code
No longer necessary as we have version control systems such as git. Remove outdated or unused code snippets to keep the codebase clean and maintainable.
### HTML Comments
HTML in source code comments is an abomination, as you can tell by reading the code below.
```java
/**
* Task to run fit tests.
* This task runs fitnesse tests and publishes the results.
*
*
* Usage:
* <taskdef name="execute-fitnesse-tests"
* classname="fitnesse.ant.ExecuteFitnesseTestsTask"
* classpathref="classpath" />
* OR
* <taskdef classpathref="classpath"
* resource="tasks.properties" />
*
* <execute-fitnesse-tests
* suitepage="FitNesse.SuiteAcceptanceTests"
* fitnesseport="8082"
* resultsdir="${results.dir}"
* resultshtmlpage="fit-results.html"
* classpathref="classpath" />
*
*/
```
### Nonlocal Information
If you must write a comment, then make sure it describes the code it appears near. Don't offer systemwide information in the context of a local comment.
### Too Much Information
Don't put interesting historical discussions or irrelevant descriptions of details into your comments.
### Inobvious Connection
The connection between a comment and the code it describes should be obvious. If you are going to the trouble to write a comment, then at least you'd like the reader to be able to look at the comment and the code and understand what the comment is talking about.
### Function Headers
Short functions don’t need much description. A well-chosen name for a small function that does one thing is usually better than a comment header.
Chapter 5 - Formatting
You should take care that your code is nicely formatted. Code formatting is about communication, and communication is key.
## Vertical Formatting
### Vertical Openness Between Concepts
Empty lines in the right places clarify which parts belong together.
Consider the difference between this bad code example and the following improvement:
```java
package fitnesse.wikitext.widgets;
import java.util.regex.*;
public class BoldWidget extends ParentWidget {
public static final String REGEXP = "'''.+?'''";
private static final Pattern pattern = Pattern.compile("'''(.+?)'''",
Pattern.MULTILINE + Pattern.DOTALL);
public BoldWidget(ParentWidget parent, String text) throws Exception {
super(parent);
Matcher match = pattern.matcher(text); match.find(); addChildWidgets(match.group(1));
}
public String render() throws Exception { StringBuffer html = new StringBuffer(""); html.append(childHtml()).append(""); return html.toString();
}
}
```
```java
package fitnesse.wikitext.widgets;
import java.util.regex.*;
public class BoldWidget extends ParentWidget {
public static final String REGEXP = "'''.+?'''";
private static final Pattern pattern = Pattern.compile("'''(.+?)'''",
Pattern.MULTILINE + Pattern.DOTALL
);
public BoldWidget(ParentWidget parent, String text) throws Exception {
super(parent);
Matcher match = pattern.matcher(text);
match.find();
addChildWidgets(match.group(1));
}
public String render() throws Exception {
StringBuffer html = new StringBuffer("");
html.append(childHtml()).append("");
return html.toString();
}
}
```
### Vertical Density
Similairly, vertical density implies close association. Lines of code that are tightly related should appear vertically dense.
### Vertical Distance
**Variable Declarations**. Variables should be declared as close to their usage as possible. Because our functions are very short, local variables should appear at the top of each function.
**Instance variables**, on the other hand, should be declared at the top of the class. This should not increase the vertical distance of these variables, because in a well-designed class, they are used by many, if not all, of the methods of the class.
**Dependent Functions**. If one function calls another, they should be vertically close, and the caller should be above the callee, if at all possible. This gives the program a natural flow. If the convention is followed reliably, readers will be able to trust that function definitions will follow shortly after their use.
**Conceptual Affinity**. Certain bits of code want to be near other bits. They have a certain conceptual affinity. The stronger that affinity, the less vertical distance there should be between them. E.g., when a group of functions perform a similar operation.
### Vertical Ordering
In general we want function call dependencies to point in the downward direction. That is, a function that is called should be below a function that does the calling. This creates a nice flow down the source code module from high level to low level.
## Horizontal Formatting
### Horizontal Openness and Density
Horizontal whitespace should separate related and unrelated elements clearly. Example:
```java
private void measureLine(String line) {
lineCount++;
int lineSize = line.length();
totalChars += lineSize;
lineWidthHistogram.addLine(lineSize, lineCount);
recordWidestLine(lineSize);
}
```
Spaces between the left and right sides of assignment statements make this separation clear.
### Horizontal Alignment
Avoid aligning variable declarations or parameters vertically, as it can emphasize the wrong aspects and distract from the code's intent.
```java
// Poor alignment
public class Example implements Base {
private Socket socket;
private inputStream input;
protected long requestProgress;
public Expediter(Socket s, inputStream input) {
this.socket = s;
this.input = input;
}
}
```
The alignment above seems to emphasize the wrong things and leads my eye away from the true intent. You are tempted to read down the list of variables without looking at their types. Instead, prefer simple and consistent alignment:
```java
// Improved alignment
public class Example implements Base {
private Socket socket;
private inputStream input;
protected long requestProgress;
public Expediter(Socket s, inputStream input) {
this.socket = s;
this.input = input;
}
}
```
### Indentation
Proper indentation provides clear visual hierarchy and defines code blocks effectively.
## Team Rules
Although every programmer has personal preferences, teams should agree on a single formatting style and stick to it. Consistency ensures the code appears cohesive and not written by a group of disagreeing individuals.
Chapter 6 - Objects and Data Structures
## Data Abstraction
Data abstraction is not just about wrapping variables in getters and setters; it's about creating abstract interfaces that encapsulate the essence of the data. A well-abstracted class provides meaningful interfaces that allow users to interact with the data without knowing its implementation details.
## Data/Object Anti-Symmetry
Objects encapsulate data behind abstractions and expose functions to operate on it. In contrast, data structures directly expose their fields and lack meaningful methods.
**Procedural Shape**
```java
public class Square {
public Point topLeft;
public double side;
}
public class Rectangle {
public Point topLeft;
public double height;
public double width;
}
public class Circle {
public Point center;
public double radius;
}
public class Geometry {
public final double PI = 3.141592653589793;
public double area(Object shape) throws NoSuchShapeException {
if (shape instanceof Square) {
Square s = (Square) shape;
return s.side * s.side;
} else if (shape instanceof Rectangle) {
Rectangle r = (Rectangle) shape;
return r.height * r.width;
} else if (shape instanceof Circle) {
Circle c = (Circle) shape;
return PI * c.radius * c.radius;
}
throw new NoSuchShapeException();
}
}
```
**Polymorphic Shape**
```java
public class Square implements Shape {
private Point topLeft;
private double side;
public double area() {
return side*side;
}
}
public class Rectangle implements Shape {
private Point topLeft;
private double height;
private double width;
public double area() {
return height * width;
}
}
public class Circle implements Shape {
private Point center;
private double radius;
public final double PI = 3.141592653589793;
public double area() {
return PI * radius * radius;
}
}
```
Objects and data structures are opposites:
> Procedural code (code using data structures) makes it easy to add new functions without changing the existing data structures. OO code, on the other hand, makes it easy to add new classes without changing existing functions.
The complement is also true:
> Procedural code makes it hard to add new data structures because all the functions must change. OO code makes it hard to add new functions because all the classes must change.
## The [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter)
A module should not know about the internal structure of the objects it manipulates. More specifically, a method `f` in a class `C` should only call methods of:
- `C`
- An object created by `f`
- An object passed as an argument to `f`
- An object held in an instance variable of `C`
The method should not invoke methods on objects that are returned by any of the allowed functions. Talk to friends, not strangers.
### Train Wrecks
The following kind of code is often called a train wreck because it looks like a series of coupled train cars. Chains of calls like this are usually considered sloppy and should be split up for clarity:
```java
Options opts = ctxt.getOptions();
File scratchDir = opts.getScratchDir();
final String outputDir = scratchDir.getAbsolutePath();
```
Does this violate the Law of Demeter? It depends on whether `ctxt`, `Options`, and `ScratchDir` are objects or data structures. If they are objects, their internal structure should be hidden, making this a clear violation. However, if they are simple data structures, they naturally expose their fields, and the Law of Demeter does not apply.
Accessor functions can blur the lines between objects and data structures. For example, this code is more concise but raises questions about Demeter violations:
```java
final String outputDir = ctxt.options.scratchDir.absolutePath;
```
The confusion would be reduced if data structures simply had public fields, while objects had private fields and public functions. However, frameworks like JavaBeans require even simple data structures to use accessors and mutators.
### Hybrids
Hybrids are structures that blend objects and data structures, leading to confusing designs. They have significant functions but also public variables or accessors/mutators that expose private variables, tempting external functions to use them like data structures.
These hybrids make it difficult to add new functions and data structures, combining the worst of both worlds. Avoid creating them, as they often result from unclear or ignorant design decisions about whether to protect functions or types.
### Hiding Structure
If `ctxt`, `options`, and `scratchDir` are objects with real behavior, their internal structure should be hidden, preventing navigation through them. To obtain the absolute path of the scratch directory:
```java
ctxt.getAbsolutePathOfScratchDirectoryOption();
```
or
```java
File scratchDir = ctxt.getScratchDirectoryOption();
String absolutePath = scratchDir.getAbsolutePath();
```
Neither option feels right. The first may lead to method bloat, and the second suggests `getScratchDirectoryOption()` returns a data structure rather than an object.
Instead of exposing its internals, an object like `ctxt` should encapsulate behavior. If the goal is to obtain a scratch file path, consider telling `ctxt` to create it directly:
```java
BufferedOutputStream bos = ctxt.createScratchFileStream(classFileName);
```
This approach allows `ctxt` to hide its internals and prevents Law of Demeter violations by keeping the calling function from navigating through unnecessary object structures.
## Data Transfer Objects
A Data Transfer Object (DTO) is a data structure class with public variables and no functions. They are particularly useful for database communication or parsing messages from sockets and often serve as the first stage in translating raw data into application objects.
A more common form is the "bean" pattern, which uses private variables with getters and setters:
```java
public class Address {
private String street;
private String streetExtra;
private String city;
private String state;
private String zip;
public Address(String street, String streetExtra, String city, String state, String zip) {
this.street = street;
this.streetExtra = streetExtra;
this.city = city;
this.state = state;
this.zip = zip;
}
public String getStreet() { return street; }
public String getStreetExtra() { return streetExtra; }
public String getCity() { return city; }
public String getState() { return state; }
public String getZip() { return zip; }
}
```
### Active Record
Active Records are specialized DTOs with public variables (or bean accessors) and navigation methods like `save` and `find`. They often map directly to database tables or other data sources.
However, issues arise when developers mix business logic into Active Records, creating hybrids that are awkward to manage.
**Solution:** Treat Active Records purely as data structures and separate business rules into distinct objects that encapsulate their own data (likely instances of Active Records).
Chapter 7 - Error Handling
Error handling is important for robust programming. However, it's essential that error handling doesn't dominate or obscure the primary logic. This chapter outlines techniques for writing clean, robust code that handles errors nicely.
## Use Exceptions Rather Than Return Codes
In older languages without exceptions, errors were handled through flags or return codes, which cluttered the calling code:
```java
public class DeviceController {
public void sendShutDown() {
DeviceHandle handle = getHandle(DEV1);
if (handle != DeviceHandle.INVALID) {
retrieveDeviceRecord(handle);
if (record.getStatus() != DEVICE_SUSPENDED) {
pauseDevice(handle);
clearDeviceWorkQueue(handle);
closeDevice(handle);
} else {
logger.log("Device suspended. Unable to shut down");
}
} else {
logger.log("Invalid handle for: " + DEV1.toString());
}
}
}
```
Using exceptions simplifies the logic:
```java
public class DeviceController {
public void sendShutDown() {
try {
tryToShutDown();
} catch (DeviceShutDownError e) {
logger.log(e);
}
}
private void tryToShutDown() throws DeviceShutDownError {
DeviceHandle handle = getHandle(DEV1);
DeviceRecord record = retrieveDeviceRecord(handle);
pauseDevice(handle);
clearDeviceWorkQueue(handle);
closeDevice(handle);
}
private DeviceHandle getHandle(DeviceID id) {
throw new DeviceShutDownError("Invalid handle for: " + id.toString());
}
}
```
Separating the device shutdown logic from error handling makes both concerns clearer.
## Write Your `Try-Catch-Finally` Statement First
A try-catch-finally block defines a transaction-like scope. Start with this block to establish consistent error handling. For instance:
1. Start with a unit test to drive the implementation:
```java
@Test(expected = StorageException.class)
public void retrieveSectionShouldThrowOnInvalidFileName() {
sectionStore.retrieveSection("invalid-file");
}
```
2. Create a stub that throws an exception:
```java
public List retrieveSection(String sectionName) {
return new ArrayList<>();
}
```
3. Implement the try-catch-finally structure:
```java
public List retrieveSection(String sectionName) {
try {
FileInputStream stream = new FileInputStream(sectionName);
stream.close();
} catch (FileNotFoundException e) {
throw new StorageException("retrieval error", e);
}
return new ArrayList<>();
}
```
4. Refactor and build up the logic using TDD, keeping the error scope well-defined.
## Use Unchecked Exceptions
Checked exceptions seemed like a great idea initially in Java, but they often violate the Open/Closed Principle. If a low-level function throws a checked exception, it requires all calling functions up the hierarchy to declare or handle it, leading to cascading changes.
Unchecked exceptions, on the other hand, maintain encapsulation. They are useful for robust software development and prevent dependency costs associated with checked exceptions.
## Provide Context with Exceptions
Each exception should provide enough context to identify the error source and location. An informative error message that describes the operation and the failure type helps in logging and debugging.
## Define Exception Classes in Terms of a Caller’s Needs
Exception handling should focus on the caller’s needs. Here's an example of a poor classification:
```java
ACMEPort port = new ACMEPort(12);
try {
port.open();
} catch (DeviceResponseException e) {
reportPortError(e);
logger.log("Device response exception", e);
} catch (ATM1212UnlockedException e) {
reportPortError(e);
logger.log("Unlock exception", e);
} catch (GMXError e) {
reportPortError(e);
logger.log("Device response exception");
}
```
Simplify this with a wrapper that returns a common exception type:
```java
LocalPort port = new LocalPort(12);
try {
port.open();
} catch (PortDeviceFailure e) {
reportError(e);
logger.log(e.getMessage(), e);
}
```
**Wrapper Implementation:**
```java
public class LocalPort {
private ACMEPort innerPort;
public LocalPort(int portNumber) {
innerPort = new ACMEPort(portNumber);
}
public void open() {
try {
innerPort.open();
} catch (DeviceResponseException | ATM1212UnlockedException | GMXError e) {
throw new PortDeviceFailure(e);
}
}
}
```
## Define the Normal Flow
Separate business logic from error handling to keep code clean. Consider this example:
```java
try {
MealExpenses expenses = expenseReportDAO.getMeals(employee.getID());
m_total += expenses.getTotal();
} catch (MealExpensesNotFound e) {
m_total += getMealPerDiem();
}
```
In this billing application, if meals are expensed, they become part of the total. If they aren't, the employee gets a meal "per diem" amount for that day. The exception clutters the logic. Use the **Special Case Pattern**, and handle the per diem amount as a special meal expense, so that it has it's own `getTotal` method:
```java
MealExpenses expenses = expenseReportDAO.getMeals(employee.getID());
m_total += expenses.getTotal();
```
**Special Case Implementation:**
```java
public class PerDiemMealExpenses implements MealExpenses {
public int getTotal() {
return /* per diem default */;
}
}
```
## Don't Return Null
Avoid returning `null` to minimize `NullPointerExceptions`. Instead, return a special case object or throw an exception.
Consider this:
```java
List employees = getEmployees();
if (employees != null) {
for(Employee e : employees) {
totalPay += e.getPay();
}
}
```
If `getEmployees()` returns `null`, we need to write a null-check. A better way would be to return an empty list instead of returning `null`:
```java
public List getEmployees() {
return Collections.emptyList(); // or a specific special case object
}
```
This way, the calling code becomes simpler:
```java
List employees = getEmployees();
for (Employee e : employees) {
totalPay += e.getPay();
}
```
# Don't Pass Null
Passing `null` into methods as an argument is equally problematic. If you receive `null` from an external API, consider wrapping it or throwing an exception to handle it safely.
Chapter 8 - Boundaries
Integrating third-party or foreign code into our own systems requires clean boundaries to prevent dependencies from creeping into our application code.
## Using Third-Party Code
There's often tension between the broad applicability of third-party interfaces and the focused needs of users. For example, `java.util.Map` provides a really broad interface.
### Example Problem
Using a generic `Map` directly can lead to issues:
```java
Map sensors = new HashMap();
Sensor s = (Sensor) sensors.get(sensorId);
```
Even with generics:
```java
Map sensors = new HashMap();
Sensor s = sensors.get(sensorId);
```
The `Map` interface provides more functionality than required and makes it hard to enforce business rules.
### Encapsulation Solution
Encapsulate third-party interfaces like `Map` to tailor them to your application's needs:
```java
public class Sensors {
private Map sensors = new HashMap<>();
public Sensor getById(String id) {
return sensors.get(id);
}
}
```
**Benefits:**
- Tailored, constrained interface
- Simplifies type management
- Easier rule enforcement
## Exploring and Learning Boundaries
Third-party packages can be difficult to integrate due to their complexity. To improve understanding, write learning tests that explore the third-party API.
### Learning Tests Example
**log4j Exploration:**
```java
@Test
public void testLogCreate() {
Logger logger = Logger.getLogger("MyLogger");
logger.info("hello");
}
@Test
public void testLogAddAppender() {
Logger logger = Logger.getLogger("MyLogger");
logger.addAppender(new ConsoleAppender(new PatternLayout("%p %t %m%n"), ConsoleAppender.SYSTEM_OUT));
logger.info("addAppenderWithStream");
}
```
**Benefits:**
- Isolates experimentation
- Helps verify expected behavior
- Detects API changes in new releases
## Using Code That Does Not Yet Exist
When dealing with undefined APIs, design your own interface and implement an adapter once the external API is available.
**Example: Transmitter Adapter**
```java
// Application-specific interface
public interface Transmitter {
void transmit(Frequency frequency, DataStream data);
}
// Adapter implementation
public class TransmitterAdapter implements Transmitter {
private final TransmitterAPI api = new TransmitterAPI();
@Override
public void transmit(Frequency frequency, DataStream data) {
api.keyOn(frequency);
api.emit(data);
}
}
```
**Benefits:**
- Keeps client code readable
- Encapsulates third-party API
- Provides a testing seam
## Clean Boundaries
Keep boundaries clean by:
1. **Wrapping Third-Party Interfaces:** Avoid passing around third-party interfaces directly.
2. **Using Adapters:** Create adapters to encapsulate interaction with external APIs.
3. **Maintaining Tests:** Write boundary tests to verify behavior at the interface.
Good boundary design accommodates change and ensures your system remains flexible and maintainable.
Chapter 9 - Unit Tests
In 1997, Test Driven Development (TDD) was unheard of. Unit tests were throwaway code that developers wrote to verify basic functionality. Nowadays, TDD is essential in modern development, ensuring that tests are written before production code.
## The Three Laws of TDD
1. **First Law:** Write a failing unit test before writing any production code.
2. **Second Law:** Write only enough of a unit test to fail.
3. **Third Law:** Write only enough production code to pass the currently failing test.
These laws ensure that tests and production code are written together in small increments, making code easier to manage and maintain.
## Keeping Tests Clean
Tests should be maintained to the same quality standards as production code. Dirty tests quickly become a liability, making them hard to maintain and causing the test suite to become a burden.
### Tests Enable the -ilities
Tests provide confidence to refactor and improve production code. Without clean tests:
- Code flexibility decreases due to fear of breaking functionality.
- Defects go unnoticed, and code quality suffers.
## Clean Tests: Readability Matters
The key to clean tests is **readability**. Tests should be clear, simple, and dense in expression.
**Example:**
```java
// Before refactoring
public void testGetPageHierarchyAsXml() throws Exception {
crawler.addPage(root, PathParser.parse("PageOne"));
crawler.addPage(root, PathParser.parse("PageOne.ChildOne"));
crawler.addPage(root, PathParser.parse("PageTwo"));
request.setResource("root");
request.addInput("type", "pages");
Responder responder = new SerializedPageResponder();
SimpleResponse response = (SimpleResponse) responder.makeResponse(new FitNesseContext(root), request);
String xml = response.getContent();
assertEquals("text/xml", response.getContentType());
assertSubString("PageOne", xml);
assertSubString("PageTwo", xml);
assertSubString("ChildOne", xml);
}
```
**After refactoring:**
```java
// Using a domain-specific testing language
public void testGetPageHierarchyAsXml() throws Exception {
makePages("PageOne", "PageOne.ChildOne", "PageTwo");
submitRequest("root", "type:pages");
assertResponseIsXML();
assertResponseContains("PageOne", "PageTwo", "ChildOne");
}
```
### Domain-Specific Testing Language
Build functions and utilities that make tests easier to read and write, forming a domain-specific language. Basically what we did with the refactoring in the previous example.
### A Dual Standard
Testing code has a different standard than production code. It should be clean, simple, and expressive, but need not be optimized for efficiency. There are things that you might never do in a production environment that are perfectly fine in a test environment.
## One Assert per Test
Having one assert per test can be beneficial but isn't a strict rule. Minimize asserts per concept to test only one concept per test function.
### Single Concept per Test
Avoid testing multiple concepts in a single test. We don’t want long test functions that go testing one miscellaneous thing after another.
## F.I.R.S.T.
Clean tests follow five key principles:
1. **Fast:** Tests should run quickly to encourage frequent runs.
2. **Independent:** Tests should not depend on each other.
3. **Repeatable:** Tests should be repeatable in any environment.
4. **Self-Validating:** Tests should provide a clear pass/fail result.
5. **Timely:** Write tests just before writing the production code. Otherwise you may not design the production code to be testable.
## Conclusion
- Clean tests are essential for clean code.
- Invent testing APIs to make tests expressive and maintainable.
- Keep tests clean, and your code will follow suit.
Chapter 10 - Classes
So far, we've focused on writing clean functions and their relationships. However, clean code extends to higher levels of organization, particularly classes.
## Class Organization
A well-organized class starts with a list of variables:
- Public static constants (if any)
- Private static variables
- Private instance variables
Public functions follow the variables, with private utilities directly related to them placed afterward, following the step-down rule.
### Encapsulation
1. **Private by Default:** Keep variables and utility functions private unless there's a good reason to expose them.
2. **Protected or Package Scope for Testing:** Consider making variables/functions protected or package scope if required by tests in the same package.
3. **Alternative Approaches:** Explore other approaches like dependency injection or design patterns before loosening encapsulation.
4. **Last Resort:** Loosening encapsulation should only be done after all other options have been considered.
## Classes Should Be Small
### Single Responsibility Principle (SRP)
> A class or module should have one, and only one, reason to change.
### Measuring Class Size
- Instead of counting lines, count responsibilities.
- A class should have a single responsibility, adhering to the **Single Responsibility Principle** (SRP).
### Example of Too Many Responsibilities
```java
public class SuperDashboard extends JFrame implements MetaDataUser {
public String getCustomizerLanguagePath() { ... }
public void setSystemConfigPath(String systemConfigPath) { ... }
public String getSystemConfigDocument() { ... }
public boolean getGuruState() { ... }
public void showObject(MetaObject object) { ... }
// ... (more than 70 methods)
}
```
### Identifying Responsibilities
- If a class name is ambiguous or contains terms like `Processor`, `Manager`, or `Super`, it's likely too broad.
- You should describe the class's purpose concisely in 25 words without "if," "and," "or," or "but."
### Cohesion
A class is cohesive when its methods and variables are co-dependent and form a logical whole. When a class has many instance variables used by subsets of methods, consider breaking it up.
The following is a very cohesive stack. Of the three methods, only `size()` fails to use both the variables.
```java
public class Stack {
private int topOfStack = 0;
List elements = new LinkedList();
public int size() {
return topOfStack;
}
public void push(int element) {
topOfStack++;
elements.add(element);
}
public int pop() throws PoppedWhenEmpty {
if (topOfStack == 0)
throw new PoppedWhenEmpty();
int element = elements.get(--topOfStack);
elements.remove(topOfStack);
return element;
}
}
```
### Maintaining Cohesion Results in Many Small Classes
When classes lose cohesion, split them. This splitting results in many small classes.
## Organizing for Change
Every change subjects us to the risk that the remainder of the system no longer works as intended. A clean system reduces the risk of change by organizing classes properly.
```java
public class Sql {
public Sql(String table, Column[] columns) { ... }
public String create() { ... }
public String insert(Object[] fields) { ... }
public String selectAll() { ... }
public String select(Criteria criteria) { ... }
public String preparedInsert() { ... }
private String columnList(Column[] columns) { ... }
private String valuesList(Object[] fields, final Column[] columns) { ... }
}
```
**Problems:**
- The `Sql` class must be opened for any changes related to SQL statements, violating SRP.
**Solution: Refactor into a Set of Closed Classes**
```java
abstract public class Sql {
public Sql(String table, Column[] columns) { ... }
abstract public String generate();
}
public class CreateSql extends Sql { ... }
public class SelectSql extends Sql { ... }
public class InsertSql extends Sql { ... }
public class SelectWithCriteriaSql extends Sql { ... }
public class SelectWithMatchSql extends Sql { ... }
public class FindByKeySql extends Sql { ... }
public class PreparedInsertSql extends Sql { ... }
public class Where { ... }
public class ColumnList { ... }
```
The code in each class becomes excruciatingly simple.
**Principle:** **Open-Closed Principle (OCP):** Classes should be open for extension but closed for modification.
### Isolating from Change
Changes are inevitable. The **Dependency Inversion Principle (DIP)** advises us to depend on abstractions rather than concrete details.
**Portfolio Interface Example:**
```java
public interface StockExchange {
Money currentPrice(String symbol);
}
public class TokyoStockExchange implements StockExchange { ... }
public class Portfolio {
private StockExchange exchange;
public Portfolio(StockExchange exchange) { this.exchange = exchange; }
public void add(int quantity, String symbol) { ... }
public Money value() { ... }
}
public class PortfolioTest {
private FixedStockExchangeStub exchange;
private Portfolio portfolio;
@Before
protected void setUp() throws Exception {
exchange = new FixedStockExchangeStub();
exchange.fix("MSFT", 100);
portfolio = new Portfolio(exchange);
}
@Test
public void GivenFiveMSFTTotalShouldBe500() throws Exception {
portfolio.add(5, "MSFT");
Assert.assertEquals(500, portfolio.value());
}
}
```
## Conclusion
- Clean classes are small, cohesive, and organized for change.
- Apply SRP, OCP, and DIP to minimize risk and improve maintainability.
- Decoupled and isolated classes improve flexibility, testability, and clarity.
Chapter 11 - Systems
> "Complexity kills. It sucks the life out of developers, it makes products difficult to plan, build, and test.”
— Ray Ozzie, CTO, Microsoft Corporation
## How Would You Build a City?
Managing a city is too complex for one person. Cities work because teams handle specific areas like water systems, power, traffic, and law enforcement. Some manage the big picture, others focus on details.
Cities have evolved modular structures and abstraction levels that allow teams and components to work effectively without fully understanding the broader system.
Similarly, software teams are organized this way, but the systems they work on often lack clear separation of concerns and abstraction levels.
## Separate Constructing a System from Using It
Construction is different from use. Separate the startup process, where objects are created and dependencies wired, from runtime logic.
Avoid mixing initialization with runtime logic, as shown below:
```java
public Service getService() {
if (service == null)
service = new MyServiceImpl(...);
return service;
}
```
While **lazy initialization** reduces startup overhead, it mixes construction with runtime logic, leading to tightly coupled dependencies and testing challenges.
Instead, modularize the startup process separately from runtime logic for a consistent dependency management strategy.
### Separation of Main
Move all construction aspects to main or modules called by main, while the rest of the system assumes objects are already constructed and wired (see Fig. 11-1). The main function handles object creation and passes them to the application, which uses them without knowing the construction details.
### Factories
Use the Abstract Factory pattern to let the application control object creation while keeping construction details separate (see Fig. 11-2). For example, an OrderProcessing app can control LineItem creation through LineItemFactoryImplementation, maintaining decoupling between construction and usage.
### Dependency Injection
Dependency Injection (DI), an application of Inversion of Control (IoC), separates construction from use by passing object creation to an authoritative mechanism (often `main` or a DI container). The class remains passive, using setter methods or constructor arguments to receive dependencies.
**Example:**
- **Spring Framework:** Well-known Java DI container using XML configuration files. Spring uses DI to automatically wire dependencies, enabling cleaner code.
**Lazy Initialization:**
- DI containers often support lazy object creation and optimizations via factories or proxies.
## Scaling Up
Cities grow from settlements into towns, then cities. Initially, roads are narrow, buildings are small, and services like power and sewage are non-existent. As population and building density increase, services are added, and roads are widened.
We can't build systems perfectly the first time. We must iterate and refactor based on changing requirements. TDD and clean code help at the code level, but architecture also needs to be scalable.
## Java Proxies
Java proxies are suitable for simple tasks like wrapping method calls but are limited to interfaces.
## Pure Java AOP Frameworks
Java frameworks like Spring AOP and JBoss AOP use proxies internally to manage aspects purely in Java, simplifying the implementation of cross-cutting concerns through declarative configurations.
## AspectJ Aspects
AspectJ offers broad support for aspect-oriented programming extending Java, allowing for detailed separation of concerns beyond what Spring AOP and JBoss AOP provide.
## Test Drive the System Architecture
Using POJOs and aspects, the architecture can evolve from simple to sophisticated without a Big Design Up Front (BDUF), facilitating flexible, just-in-time decision-making and optimal system evolution.
## Use Standards Wisely, When They Add Demonstrable Value
While standards are beneficial for reusability and integration, they should be adopted cleverly to ensure they add value and do not distract from focusing on delivering customer needs.
## Systems Need Domain-Specific Languages
Domain-Specific Languages (DSLs) help minimize the gap between domain concepts and their implementation, allowing code to express high-level policies and low-level details coherently.
## Conclusion
Systems must be clean too. Invasive architecture overwhelms domain logic, compromising agility. If domain logic is obscured, quality suffers, bugs hide, and implementing stories becomes harder.
- Clean separation of concerns is essential.
- Architecture should grow incrementally, like cities, from simple to complex.
- Maintain minimal coupling to retain the ability to adapt.
Ultimately, separate the system's construction from its use, allowing it to scale and evolve with clarity and agility.
Chapter 12 - Emergence
Kent Beck's four rules of simple design:
## 1. Runs All the Tests
Ensure the system works as intended and passes comprehensive tests.
## 2. Contains no Duplication
Eliminate duplicate code to reduce complexity and improve clarity.
- Extract common methods to avoid repetitive patterns.
- Use design patterns like TEMPLATE METHOD to handle higher-level duplication.
## 3. Expresses the Intent of the Programmer
- Use clear names, standard nomenclature (e.g., design patterns), and concise functions.
- Write unit tests that serve as documentation.
## 4. Minimizes the Number of Classes and Methods
Keep the overall class and method count low, but prioritize the first three rules.
Chapter 13 - Concurrency
> “Objects are abstractions of processing. Threads are abstractions of schedule.”
— James O. Coplien
**Writing clean concurrent programs is hard.** Single-threaded code is much easier to write and maintain, while concurrent code can often appear correct on the surface but be fundamentally broken under stress. This chapter explores the necessity of concurrent programming, the difficulties it presents, and recommendations for writing clean concurrent code.
## Why Concurrency?
Concurrency is a strategy that decouples *what* gets done from *when* it gets done, providing significant structural and performance benefits. It transforms a monolithic program into multiple small collaborating entities, simplifying comprehension and separation of concerns.
However, this decoupling isn't straightforward. For instance, while web containers allow servlets to execute asynchronously and independently, programmers must remain vigilant to avoid errors. Concurrent programming is not just about improving structure; it also handles performance constraints like reducing response times and improving throughput by handling tasks in parallel.
### Myths and Misconceptions
Concurrency brings significant challenges, and several misconceptions exist:
- **Performance Improvement:** Concurrency doesn't always lead to better performance. It helps only when there’s substantial idle time that can be shared among threads.
- **Design Changes:** Concurrent programming often requires a fundamental design shift due to decoupling of *what* from *when*.
- **Container Management:** Understanding concurrency remains crucial even within managed environments like web or EJB containers.
## Concurrency Defense Principles
### Single Responsibility Principle (SRP)
Concurrency implementation is a responsibility in itself and should be separated from other code. Isolating concurrency logic simplifies changes and minimizes the risk of errors.
### Limit Data Scope
Restrict access to shared data to minimize synchronization issues.
### Use Copies of Data
If possible, copy data instead of sharing it, treating copies as read-only.
### Threads Should Be as Independent as Possible
Write threads to exist in their own world, avoiding shared data wherever possible.
## Know Your Library
Java 5's `java.util.concurrent` package provides thread-safe collections like `ConcurrentHashMap`, and several utility classes like:
- **ReentrantLock:** Allows locking across different methods.
- **Semaphore:** Classic lock with a count.
- **CountDownLatch:** Waits for events before releasing all waiting threads.
## Know Your Execution Models
Several concurrency execution models include:
- **Producer-Consumer:** Producers create work and place it in a queue; consumers take tasks from the queue for processing.
- **Readers-Writers:** Balancing the needs of multiple readers and occasional writers without compromising performance or causing starvation.
- **Dining Philosophers:** Philosophers (threads) compete for shared resources, potentially leading to deadlock.
## Beware Dependencies Between Synchronized Methods
Multiple synchronized methods on a shared object may lead to subtle bugs. Consider client-based, server-based, or adapted server locking.
## Keep Synchronized Sections Small
Synchronized code introduces locks, which are expensive and should only protect critical sections.
## Writing Correct Shut-Down Code is Hard
Graceful shutdowns often lead to deadlocks if not handled correctly. For instance, child threads waiting on signals or resources may block the parent thread from shutting down.
**Recommendation:** Implement shutdown logic early and use well-established algorithms.
## Testing Threaded Code
Concurrency issues can be subtle and sporadic. To effectively test threaded code:
- **Treat Spurious Failures Seriously:** Investigate every anomaly as a potential threading issue.
- **Get Non-threaded Code Working First:** Ensure non-threaded code works outside threads.
- **Make Threaded Code Pluggable and Tunable:** Configure threaded code to handle different testing scenarios and tune the number of threads dynamically.
- **Run with More Threads than Processors:** Expose synchronization flaws by forcing frequent task swapping.
- **Test on Multiple Platforms:** Different operating systems have unique threading policies.
- **Instrument Code to Force Failures:** Add calls like `sleep()`, `yield()`, or `priority()` to expose threading issues.
Chapter 14 - Successive Refinement
This chapter provides a detailed case study showcasing how a command-line argument parsing module named `Args` was incrementally refactored and cleaned. Initially functional but unscalable, the module was transformed through successive refinement, demonstrating the importance of continuous improvement and clean coding practices.
## Initial Module: Args
**Initial Design and Problem:**
- The original Args module was written to parse command-line arguments using a format string.
- The format string defined argument types like booleans, integers, and strings (e.g., `l`, `p#`, `d*`).
- The module parsed and returned argument values efficiently but was plagued by poor structure and scaling issues.
**Listing Example:**
```java
public static void main(String[] args) {
try {
Args arg = new Args("l,p#,d*", args);
boolean logging = arg.getBoolean('l');
int port = arg.getInt('p');
String directory = arg.getString('d');
executeApplication(logging, port, directory);
} catch (ArgsException e) {
System.out.printf("Argument error: %s\n", e.errorMessage());
}
}
```
## Rough Draft
**Code Smells in the Initial Implementation:**
- Overly complex with too many instance variables.
- Error messages contained hardcoded strings like "TILT".
- The implementation was cluttered with try-catch blocks and redundant collections.
**Observations:**
- "Festering pile" of code due to the addition of multiple argument types.
- For instance, adding `String` and `Integer` arguments resulted in messy, hard-to-maintain code.
## Refactoring Process
**ArgumentMarshaler Concept:**
- Recognizing the need for a uniform approach to handling argument types, the `ArgumentMarshaler` interface was introduced:
```java
public interface ArgumentMarshaler {
void set(Iterator currentArgument) throws ArgsException;
Object get();
}
```
**Successive Refinement Steps:**
1. **Initial Incremental Refactoring:**
- Introduced `ArgumentMarshaler` interface with `BooleanArgumentMarshaler`, `StringArgumentMarshaler`, and `IntegerArgumentMarshaler` implementations.
- Simplified parsing logic by centralizing error handling.
2. **Reducing Code Duplication:**
- Consolidated maps of different argument types into a single map of `ArgumentMarshaler`.
- Eliminated redundant functions and streamlined error handling.
3. **Further Modularization:**
- Split error-handling logic into its own class, `ArgsException`.
- Gradually moved argument parsing logic into individual `ArgumentMarshaler` derivatives.
## Final Solution
**Refined and Modular Args Module:**
- The final implementation was clean, modular, and scalable, using clear separation of concerns.
- Adding a new argument type required minimal changes.
**Example of Adding a New Type (Double):**
- **DoubleArgumentMarshaler Implementation:**
```java
private class DoubleArgumentMarshaler implements ArgumentMarshaler {
private double doubleValue = 0;
public void set(Iterator currentArgument) throws ArgsException {
try {
doubleValue = Double.parseDouble(currentArgument.next());
} catch (Exception e) {
throw new ArgsException(ArgsException.ErrorCode.INVALID_DOUBLE);
}
}
public Object get() {
return doubleValue;
}
}
```
- **Integration into the Args Module:**
```java
private void parseSchemaElement(String element) throws ArgsException {
char elementId = element.charAt(0);
String elementTail = element.substring(1);
if (elementTail.equals("##")) {
marshalers.put(elementId, new DoubleArgumentMarshaler());
}
}
```
## Key Principles and Recommendations
1. **Single Responsibility Principle (SRP):**
- The Args module should handle only command-line argument parsing, while error messages belong to `ArgsException`.
2. **Incremental Refactoring:**
- Make small, incremental changes, ensuring the system keeps running at each step.
3. **Continuous Testing:**
- A comprehensive suite of unit and acceptance tests ensures stability throughout refactoring.
Chapter 15 - JUnit Internals
This chapter explores a module from the JUnit testing framework, specifically focusing on the `ComparisonCompactor` class. The chapter analyzes the initial implementation of the class, critiques its structure, and demonstrates how it was refactored for improved clarity and functionality. The refactoring is guided by the "Boy Scout Rule," which encourages leaving code cleaner than it was found.
## JUnit and `ComparisonCompactor`
**JUnit's Background:**
- JUnit is a popular Java testing framework created by Kent Beck and Eric Gamma.
- The `ComparisonCompactor` class was designed to identify differences between two strings and present them in a compact form, highlighting differences for better error messages.
**Module Requirements:**
- Given two differing strings like `ABCDE` and `ABXDE`, `ComparisonCompactor` should produce a message like `<...B[X]D...>` to highlight the difference.
**Initial Unit Tests:**
- Listing 15-1 shows a series of tests for `ComparisonCompactor`, covering various edge cases such as strings with common prefixes and suffixes, null values, and overlapping matches.
**Initial Implementation:**
- Listing 15-2 contains the original `ComparisonCompactor` class with features like:
- Finding common prefixes and suffixes between two strings.
- Compacting the differing portions of strings for better error messages.
- Usage of constants like `ELLIPSIS`, `DELTA_START`, and `DELTA_END`.
## Refactoring Process
**Critique of Initial Code:**
- The initial code was fairly clean but had opportunities for improvement:
- The use of member variables prefixed with `f`.
- Unencapsulated conditional logic at the start of the `compact` function.
- Ambiguous naming of certain variables.
- Complex calculations and expressions.
**Refactoring Steps:**
1. **Encapsulation and Naming:**
- Removed `f` prefixes and encapsulated conditionals in methods like `shouldNotCompact`.
2. **Simplified Logic:**
- Reversed conditional statements to improve clarity.
- Renamed `compact` to `formatCompactedComparison`.
3. **Temporal Coupling:**
- Separated finding common prefixes and suffixes for better ordering.
4. **Consistent Conventions:**
- Standardized suffix calculations and naming.
5. **Extract and Refine Functions:**
- Extracted methods for prefix and suffix calculation.
- Used functions like `computeCommonPrefix` and `computeCommonSuffix`.
## Final Implementatio:
Listing 15-5 presents the final implementation of `ComparisonCompactor`:
- Refined structure, improved naming, and encapsulated methods.
- Clearly separated analysis functions (prefix/suffix calculations) from synthesis functions (compacting).
## Lessons Learned
- **The Boy Scout Rule:** Leave code cleaner than you found it.
- **Iterative Refactoring:** Refactoring is iterative and often involves undoing previous decisions.
- **Clear Separation:** Separate analysis and synthesis functions for clarity.
- **Naming Conventions:** Use precise and meaningful names for variables and methods.
Chapter 16 - Refactoring SerialDate
This chapter focuses on the process of refactoring the `SerialDate` class from the JCommon library, originally authored by David Gilbert. Despite acknowledging the high quality of Gilbert's work, the chapter illustrates a thorough critique and refactoring of the `SerialDate` code, highlighting the importance of continuous improvement and peer reviews in software development.
## Activities in Refactoring
1. **Initial Evaluation and Testing:**
- The existing unit tests for `SerialDate` covered only about 50% of the code. Additional tests were developed to increase coverage and reveal untested functionality.
- Specific untested methods were identified and new tests were added to ensure they function as expected, raising the test coverage to 92%.
2. **Identifying and Fixing Bugs:**
- Various bugs were discovered through the enhanced testing process, including logic errors in date calculations and handling. These were systematically fixed.
3. **Code and Logic Simplification:**
- Several methods were simplified or entirely rewritten to improve clarity and reduce complexity. This included merging redundant methods and eliminating unnecessary parameters.
4. **Improving Naming Conventions:**
- Method and variable names were revised to be more descriptive and intuitive.
5. **Enhancing Code Structure:**
- The structure of `SerialDate` was significantly changed. Functions were better organized, and unnecessary code was removed.
6. **Adopting Modern Java Practices:**
- Refactoring involved using enums instead of constants for clarity and safety, implementing factory patterns for object creation, and removing deprecated or redundant code constructs.
## Refactoring Techniques Used
- **Encapsulation and Abstraction:**
- Increasing encapsulation by hiding implementation details and abstracting functionalities into appropriate scopes.
- **Code Consolidation:**
- Combining similar functions and removing duplicate code to streamline the class structure.
- **Enum Utilization:**
- Replacing constant values with enums for better type safety and clarity.
- **Error Handling:**
- Improved error handling by replacing vague return types (like integer codes) with exceptions, which makes the code more robust and easier to debug.
Chapter 17 - Smells and Heuristics
## Comments
- **C1: Inappropriate Information** - Comments should only contain technical notes relevant to the code and design.
- **C2: Obsolete Comment** - Obsolete comments must be updated or removed promptly.
- **C3: Redundant Comment** - Avoid comments that state what the code clearly communicates.
- **C4: Poorly Written Comment** - Ensure comments are concise, clear, and grammatically correct.
- **C5: Commented-Out Code** - Remove unused code snippets; rely on version control for history.
## Environment
- **E1: Build Requires More Than One Step** - A build process should be executable via a single command.
- **E2: Tests Require More Than One Step** - Testing should be possible with one click in an IDE or a single command line instruction.
## Functions
- **F1: Too Many Arguments** - Limit arguments to three or fewer to maintain clarity.
- **F2: Output Arguments** - Avoid output arguments; modify the object state internally instead.
- **F3: Flag Arguments** - Eliminate boolean flags which complicate function purpose.
- **F4: Dead Function** - Remove functions that are never called.
## General
- **G1: Multiple Languages in One Source File** - Restrict source files to a single programming language where possible.
- **G2: Obvious Behavior Is Unimplemented** - Ensure intuitive behavior in functions and classes.
- **G3: Incorrect Behavior at the Boundaries** - Thoroughly test boundary conditions.
- **G4: Overridden Safeties** - Avoid disabling safety mechanisms that protect the integrity of code.
- **G5: Duplication** - Use abstraction to reduce and manage duplicated code.
- **G6: Code at Wrong Level of Abstraction** - Ensure that code at different abstraction levels is placed in appropriate containers.
- **G7: Base Classes Depending on Their Derivatives** - Emphasize modularity in your design.
- **G8: Too Much Information** - Minimize the complexity by limiting what is going on within a class or function.
- **G9: Dead Code** - Remove any code that is not executed.
- **G10: Vertical Separation** - Place definitions for variables and functions near their points of use.
- **G11: Inconsistency** - Adopt a coding standard and consistently follow it to avoid surprises.
- **G12: Clutter** - Eliminate dead code that adds unnecessary clutter.
- **G13: Artificial Coupling** - Prefer clarity over convenience and avoid grouping unrelated pieces of code.
- **G14: Feature Envy** - Ensure that a class’s methods do not overly rely on or interfere with another class’s methods.
- **G15: Selector Arguments** - Avoid using superfluous arguments in function calls.
- **G16: Obscured Intent** - Code should be transparent and easy to understand, not cryptic.
- **G17: Misplaced Responsibility** - Assign responsibilities to functions clearly, using descriptive names as guides.
- **G18: Inappropriate Static** - Favor instance methods over static methods unless necessary.
- **G19: Use Explanatory Variables** - Use descriptive variable names extensively to clarify code intentions.
- **G20: Function Names Should Say What They Do** - Function names should clearly reflect what they accomplish.
- **G21: Understand the Algorithm** - Fully grasp the functioning of algorithms beyond just passing tests; consider refactoring for deeper insights.
- **G22: Make Logical Dependencies Physical** - Ensure dependencies within the code are explicitly defined and understood.
- **G23: Prefer Polymorphism to If/Else or Switch/Case** - Utilize polymorphism over conditional statements for cleaner and more maintainable code.
- **G24: Follow Standard Conventions** - Adhere to team or community conventions consistently across your project.
- **G25: Replace Magic Numbers with Named Constants** - Use named constants instead of direct numbers to enhance code readability.
- **G26: Be Precise** - Consider and rigorously test all possible outcomes of your code.
- **G27: Structure Over Convention** - Make design decisions based on a logical structure rather than merely following convention.
- **G28: Encapsulate Conditionals** - Focus on making conditional logic clear and well encapsulated.
- **G29: Avoid Negative Conditionals** - Use positive conditions where possible to improve code readability.
- **G31: Hidden Temporal Couplings** - Explicitly indicate any temporal dependencies in your code.
- **G32: Don’t Be Arbitrary** - Your code structure should clearly communicate its purpose and rationale.
- **G33: Encapsulate Boundary Conditions** - Keep boundary calculations within functions to prevent widespread impacts.
- **G34: Functions Should Descend Only One Level of Abstraction** - Maintain a single level of abstraction within functions to simplify understanding.
- **G35: Keep Configurable Data at High Levels** - Place configurable elements at high levels within your architecture for easier modification.
- **G36: Avoid Transitive Navigation** - Design modules to interact only with direct neighbors to reduce dependencies and increase modularity.
## Names
- **N1: Choose Descriptive Names** - Select names that effectively describe what the code does.
- **N2: Choose Names at the Appropriate Level of Abstraction** - Names should reflect the abstraction level of their context.
- **N3: Use Standard Nomenclature Where Possible** - Employ commonly understood names within the domain.
- **N4: Unambiguous Names** - Names should clearly communicate their role without ambiguity.
- **N5: Use Long Names for Long Scopes** - The scope of a name should dictate its length; longer names for broader scopes.
- **N6: Avoid Encodings** - Don't embed type or scope information in variable names.
- **N7: Names Should Describe Side-Effects** - When naming your function, factor in its side-effects to ensure the name accurately reflects its behavior.
## Tests
- **T1: Insufficient Tests** - Ensure that the test suite comprehensively covers potential faults.
- **T2: Use a Coverage Tool!** - Leverage tools to highlight untested or under-tested parts of the code.
- **T3: Don’t Skip Trivial Tests** - Even simple tests can prevent future bugs and clarify intent.
- **T4: An Ignored Test is a Question about an Ambiguity** - Ignoring a test raises concerns about the clarity of the code.
- **T5: Test Boundary Conditions** - While common paths are often tested, it's important to remember to test the boundary conditions as well.
- **T6: Exhaustively Test Near Bugs** - Bugs often cluster together, so when one is found, it's important to thoroughly test the surrounding area for others.
- **T7: Patterns of Failure Are Revealing** - Well-organized test cases can help identify recurring patterns of failure.
- **T8: Test Coverage Patterns Can Be Revealing** - Looking at the code that is or is not executed by the passing tests gives clues to why the
failing tests fail.
- **T9: Tests Should Be Fast** - A slow test is a test that won’t get run.
### Misleading Comments
Even with the best intentions, a programmer can make a statement in his comments that isn't precise enough to be accurate. Ensure accuracy in your comments to prevent misinformation.
### Mandated Comments
Mandatory comment policies often lead to clutter and misinformation. Prefer meaningful documentation over mandatory comments. Here the comments are redundant.
```java
/**
*
* @param title The title of the CD
* @param author The author of the CD
* @param tracks The number of tracks on the CD
* @param durationInMinutes The duration of the CD in minutes
*/
public void addCD(String title, String author, int tracks, int durationInMinutes) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cd.tracks = tracks;
cd.duration = duration;
cdList.add(cd);
}
```
### Journal Comments
Back in the day people used to add a comment to the start of a module every time they edited it. Example:
```java
/*
* Changes (from 11-Oct-2001)
* --------------------------
* 11-Oct-2001 : Re-organised the class and moved it to new package com.jrefinery.date (DG);
* 05-Nov-2001 : Added a getDescription() method, and eliminated NotableDate class (DG);
* 12-Nov-2001 : IBD requires setDescription() method, now that NotableDate class is gone (DG); Changed getPreviousDayOfWeek(),
getFollowingDayOfWeek() and getNearestDayOfWeek() to correct bugs (DG);
* 05-Dec-2001 : Fixed bug in SpreadsheetDate class (DG);
*/
```
Today we have source code control systemsfor this type of logs.
### Noise Comments
The comments in the follow examples don't provide new value.
```java
/**
* Default constructor.
*/
protected AnnualDateRule() {
}
/** The day of the month. */
private int dayOfMonth;
```
### Don’t Use a Comment When You Can Use a Function or a Variable
Example:
```java
// does the module from the global list