Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

assertThat(x, is(3)); assertThat(x, is(not(4))); assertThat(responseString, either(containsString("color")).or(containsString("colour"))); assertThat(myList, hasItem("3")); 

with the traditional style of assertEquals:

assertEquals(3, x); 

When I look at the assertEquals statement, it is not clear which parameter is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Another key to writing self-documenting code is to wrap any bit of logic that is not clear in a method call with a clear name.

if( (x < 3 || x > 17) && (y < 8 || y > 15) ) 

becomes

if( xAndYAreValidForOperationJ22( x, y ) ) // or similar... 

Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

assertThat(x, is(3)); assertThat(x, is(not(4))); assertThat(responseString, either(containsString("color")).or(containsString("colour"))); assertThat(myList, hasItem("3")); 

with the traditional style of assertEquals:

assertEquals(3, x); 

When I look at the assertEquals statement, it is not clear which parameter is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Another key to writing self-documenting code is to wrap any bit of logic that is not clear in a method call with a clear name.

if( (x < 3 || x > 17) && (y < 8 || y > 15) ) 

becomes

if( xAndYAreValid( x, y ) ) // or similar... 

Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

assertThat(x, is(3)); assertThat(x, is(not(4))); assertThat(responseString, either(containsString("color")).or(containsString("colour"))); assertThat(myList, hasItem("3")); 

with the traditional style of assertEquals:

assertEquals(3, x); 

When I look at the assertEquals statement, it is not clear which value is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

assertThat(x, is(3)); assertThat(x, is(not(4))); assertThat(responseString, either(containsString("color")).or(containsString("colour"))); assertThat(myList, hasItem("3")); 

with the traditional style of assertEquals:

assertEquals(3, x); 

When I look at the assertEquals statement, it is not clear which parameter is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Another key to writing self-documenting code is to wrap any bit of logic that is not clear in a method call with a clear name.

if( (x < 3 || x > 17) && (y < 8 || y > 15) ) 

becomes

if( xAndYAreValidForOperationJ22( x, y ) ) // or similar...