Empathic Programming - How to write comprehensible code

Clean Code

How to write comprehensible Code

regarding cognitive abilities of human mind

01.03.2011
XPUG Rhein / Main
Mario Gleichmann

Mario Gleichmann

twitter: @mariogleichmann

blog: gleichmann.wordpress.com (brain driven development)

site: www.mg-informatik.de

mail: mario.gleichmann@mg-informatik.de

The cost of Software Development

Intellectual Complexity

''Making changes is generally easy
if you exactly know what needs to be changed''

Programming is a cognitive process

Simplicity

Intellectually manageable programs

Communication

'existing code is much more read than new code is written'

What's the goal ?
def find( start :Char, end :Char, pths :List[ (Char,Char) ] ) :List[ (Char,Char) ] = {

var rout = (start,start) :: Nil
var dends :List[(Char,Char)] = Nil

while( !rout.isEmpty && rout.head._2 != end ){

var conts = from( rout.head._2, pths )
.filter( pth => !dends.contains( pth ) && !rout.contains( pth ) )

if( conts.isEmpty && !rout.isEmpty ) {

dends = rout.head :: de
rout = rout.tail
}
else{
rout = conts.iterator.next :: rte
}
}
rout.reverse.tail
}

'G'
'F'
'I'

'B'

'C'
'A'
'H'

'D'

'G'
'E'

What's the goal ?
def findRoute( start :WayPoint, target :WayPoint, map :Set[Path] ) :Sequence[Path] = {

var route = new Stack[Path]
var deadEnds :Set[Path] = new HashSet[Path]

route push Path( start, start )

while( !route.isEmpty && route.top.endPoint != target ){

var continuingPaths = pathsFrom( route.top.endPoint, map )
.without( deadEnds ).without( route )

if( continuingPaths.isEmpty && !route.isEmpty ) {

deadEnds += route.pop
}
else{
route push continuingPaths.first
}
}
route.reverse
}

Hypothesis
&
Verification

public class PrimeGenerator {

static int[] sieveUpTo( int maxValue ){

if( maxValue < 2 ) return new int[0];

boolean[] grid = new boolean[maxValue + 1];
for( int i = 0; i <= maxValue; i++ ){
grid[i] = true;
}

grid[0] = grid[1] = false;

for( int i = 2; i < Math.sqrt( maxValue + 1 ) + 1; i++ ){
if( grid[i] ){
for( int j = 2*i; j <= maxValue; j += i ){
grid[j] = false;
}
}
}
…
}

Concepts

Push

Pop
Stack

Concepts

Store Push

Pop
Stack

Concepts
Not
Store 'lose' Push
Elements

Pop
Stack

Concepts
Not
Store 'lose' Push
Elements

Pop
Collection Stack

Concepts
Not
Store 'lose' Push
Elements

Pop
Collection Stack

Add Remove Iterate
Elements Elements Elements

Concepts

Store Push

Pop
Stack

LIFO

Concepts

Store Push

Pop
Stack

LIFO

FIFO

Concepts

Store Push

Pop
Stack

LIFO

Queue
FIFO
FIFO

Concepts

Store Push

Pop
Collection Stack

LIFO
AddAddAdd
Elements
Elements
Elements Queue
FIFO
FIFO

public class Folding {

public static <T> T fold( List<T> list, Monoid<T> monoid ){

return list.isEmpty() ?
monoid.unit() :
monoid.conjunct( head( list ), fold( tail( list ), monoid ) );
}

private static <T> T head( List<T> list ){
return list.isEmpty() ? null : list.get( 0 );
}

private static <T> List<T> tail( List<T> list ){
return list.size() >= 2 ? list.subList( 1, list.size() ) : EMPTY_LIST;
}
}

public interface Monoid<T> {

public T unit();

public T conjunct( T t1, T t2 );
}

public class MonoidInstanceTest extends TestCase{
...

public void testStringAsMonoid(){
assertEquals( "helloworld", stringMonoid.conjunct( "hello", "world" ) );
assertEquals( "hollamundo", stringMonoid.conjunct( "hola", "mundo" ) );

assertEquals( "hola", stringMonoid.conjunct( "hola", stringMonoid.unit() ) );
assertEquals( "hola", stringMonoid.conjunct( stringMonoid.unit(), "hola" ) );
}

public void testIntegerAsMonoid(){
assertEquals( 6, poductIntMonoid.conjunct( 2, 3 ) );
assertEquals( 42 , productIntMonoid.conjunct( 7, 6 ) );

assertEquals( 11, productIntMonoid.conjunct( 11, productIntMonoid.unit() ) );
assertEquals( 11, productIntMonoid.conjunct( productIntMonoid.unit(), 11 ) );
}
...
}

public class MonoidTest extends TestCase{
...
private static <T> void assertAssociativity( Monoid<T> monoid, T t1, T t2, T t3 ){

assertEquals( monoid.conjunct( t1, monoid.conjunct( t2, t3 ) ),
monoid.conjunct( monoid.conjunct( t1, t2 ), t3 ) );
}

private static <T> void assertNeutrality( Monoid<T> monoid, T value ){

assertEquals( monoid.conjunct( value, monoid.unit() ), value );
assertEquals( monoid.conjunct( monoid.unit(), value ), value );
}

public void testMonoidInstances(){
assertAssociativity( stringMonoid, "s1", "s2", "s3" );
assertNeutrality( stringMonoid, "s1" );
...
assertAssociativity( productSumMonoid, 1, 2, 3 );
assertNeutrality( productSumMonoid, 1 );
}
}

public class Monoids {

public static Monoid<String> stringMonoid = new Monoid<String>(){

public String unit() { return ""; }

public String conjunct(String t1, String t2) { return t1 + t2; }
};

public static Monoid<Integer> productIntMonoid = new Monoid<Integer>(){

public Integer unit() { return 1; }

public Integer conjunct(Integer t1, Integer t2) { return t1 * t2; }
};

...

public class Monoids {

...

public static Monoid<Integer> sumIntMonoid = new Monoid<Integer>(){

public Integer unit() { return 0; }

public Integer conjunct(Integer t1, Integer t2) { return t1 + t2; }
};

...

public class FoldTest extends TestCase{

public void testStringConcat(){

assertEquals( "Hello world !!!",
fold( asList( "Hello", " ", "world" + " " + "!!!" ), stringMonoid ) );
}

public void testSum(){

assertEquals( 15, fold( asList( 1, 2, 3, 4, 5 ), sumIntMonoid ).intValue() );
}

public void testProduct(){

assertEquals( 120, fold( asList( 1, 2, 3, 4, 5 ), productIntMonoid ).intValue() );
}

...

public reorderBook( String isbn ){
...

if( isbn.substring( 0, 2 ).equals( ''978'' ){

pubNr = isbn.substring( 6, 10 );
}
else{

}
...
}

public reorderBook( String isbn ){
...

if( isbn.substring( 0, 2 ).equals( ''978'' ){

}
else{

}
...
}
ISBN is NOT a String !!!

public interface Isbn {
public Region getRegion(){ ... }
public Integer getPublisherNumber(){ ... }
public Integer getTitelNumber(){ ... }
public Integer getChecksum(){ ... }
public boolean isValid(){ ... }
}

ISBN is a concept in its own right !!!

public reorderBook( Isbn isbn ){
...
isbn.getPublisherNumber();
...
}

public boolean isValidLaufzeit( Vertrag vertrag ){

GregorianCalendar start = vertrag.getStart();
GregorianCalendar end = vertrag.getEnd();

int tagesdifferenz = 0;
if (start != null && end != null) {
int startJahr = start.get(Calendar.YEAR);
int endJahr = end.get(Calendar.YEAR);
int tageImStartJahr = start.get(Calendar.DAY_OF_YEAR);
int tageImEndJahr = end.get(Calendar.DAY_OF_YEAR);
int aktuellesJahr = startJahr;

while (aktuellesJahr <= endJahr) {
if (aktuellesJahr == startJahr) {
if (aktuellesJahr == endJahr) {
tagesdifferenz += tageImEndJahr - tageImStartJahr;
} else {
tagesdifferenz += start.isLeapYear(startJahr) ?
(366 - tageImStartJahr) : (365 - tageImStartJahr);
}
} else if (aktuellesJahr == endJahr) {
tagesdifferenz += tageImEndJahr;
} else {
tagesdifferenz += start.isLeapYear(aktuellesJahr) ? 366 : 365;
}
aktuellesJahr++;
}
}
return tagesdifferenz > 365 && tagesdifferenz < 999;
}

public void createOrder( int itemId, Date shippingDate ){

Date today = new Date();

long start = today.getTime();
long end = shippingDate.getTime();

BigDecimal diff = new BigDecimal( start - end );

int days = diff.divideToIntegralValue(
new BigDecimal( 1000 * 60 * 60 * 24 ) ).intValue();

if( days > 14 ) rejectOrder();

// ...
}

public boolean isValidLaufzeit( Vertrag vertrag ){

TimeInterval interval = vertrag.getLaufzeit();

return
interval.toDuration().inYears() > ONE_YEAR
&&
interval.toDuration().inYears() < THREE_YEARS;
}

public void createOrder( int ItemId, Date shippingDate ){

Duration duration = new Duration( today(), shippingDate );

if( duration.inDays() > 14 ) rejectOrder();

// ...
}

String separator ='' '';
String query = ''select '';
if( ... ) query += '' name '';
if( ... ) query = query + separator + '' alter '', separator = '', '';
query += '' from person '';
if( existFilter ){
query += '' where ''
if( ... ) query += '' stadt = '' + stadt; separator = '' and '';
else{
query += '' stadt in ( '';
for( String stadt : staedte )
query += stadt + inSeparator; inSeparator = '', '';
query += '' ); separator = '' and ''
}
...

if( ... ) query += '' name '';
Do you see the core idea ?
if( existFilter ){
(Hint: it's NOT about String Handling)
else{
}
...

if( ... ) query += '' name '';
Building SQL-Statements ...
if( existFilter ){
… is NOT about String Handling
else{
}
...

Query personQuery = Query.onTable( ''Person'' )

personQuery.select( ''name'' )
personQuery.select( ''alter '' )

personQuery.add( criteria( ''stadt'' ).equals( stadt ) );

personQuery.add( criteria( ''stadt'' ).in( staedte ) );

...

String separator ='' ''; … by the way ...
if( ... ) query += '' name '';
if( existFilter ){
else{
}
...

String separator ='' ''; … anybody missed that ?
if( ... ){ query += '' name ''; separator = '', ''; }
if( existFilter ){
else{
}
...

''Look, a Composite ...'

Directory ''delete'

File File Directory ''delete'

''delete' ''delete'

File File

''delete' ''delete'

''Look, another Composite ...''

UI Panel ''draw'

UI Text UI Input UI Panel ''draw'

''draw' ''draw'

UI Text UI Selection
''draw' ''draw'

AbstractComposite

operation()
add( Composite)
remove( Composite )
childs() : List<Comp.>

Node Composite

operation() operation()
add( Composite)
remove( Composite )
childs() : List<Comp.>

Is this a Composite ?

AtLeastOneAuthProvider ''authenticate'

LdapAuthProvider DatabaseAuth. UnanimousAuthProvider
''authenticate' ''authenticate'

CertificateAuth. AccessAuth.
''authenticate' ''authenticate'

... and this ?

CEO ''salary'

Employee Employee CIO

''salary' ''salary'

Employee Employee
''salary' ''salary'

Collection

generalization

List Set Bag

Queue Stack
< discrimination >

FIFO LIFO

public static Integer sum( Stack<Integer> vals ){
int sum = 0;
for( int val : vals ) sum += val;
return sum;
}

public static Integer sum( Stack<Integer> vals ){
int sum = 0;
return sum;
}

sum( new Stack<Integer>(){{ push(1); push(2); push(3); }};

sum( new ArrayList<Integer>(){{ add(1); add(2); add(3) }};

public static Integer sum( List<Integer> vals ){
int sum = 0;
return sum;
}



sum( new HashSet<Integer>(){{ add(1); add(2); add(3) }};

public static Integer sum( Collection<Integer> vals ){
int sum = 0;
return sum;
}



sum( new HashSet<Integer>(){{ add(1); add(2); add(3) }};

public class QueueTest extends TestCase {

private Queue<Integer> queue = null;
public void setUp() throws Exception{
queue = new ...
queue.add( 10 );
queue.add( 3 );
queue.add( 7 );
queue.add( 5 );
}

public testQueuePolling{
assertEquals( ? , queue.poll() );
assertEquals( ?? , queue.poll() );
assertEquals( ??? , queue.poll() );
assertEquals( ???? , queue.poll() );
}
}


queue = new ArrayBlockingQueue<Integer>();
queue.add( 10 );
queue.add( 3 );
queue.add( 7 );
queue.add( 5 );
}

assertEquals( 10 , queue.poll() );
}
}


queue = new PriorityQueue<Integer>();
queue.add( 10 );
queue.add( 3 );
queue.add( 7 );
queue.add( 5 );
}

}
}

Collection

generalization

List Set Bag

Queue

Stack

PriorityQueue ArrayQueue

HPFO < discrimination >
FIFO

public static List<Integer> multiplesOf( int factor, int limit ){

List<Integer> collect = new ArrayList<Integer>();

for( int i = 1; i * factor <= limit; i++ ){
collect.add( i * factor );
}
return collect;
}
vs.

public static Set<Integer> multiplesOf( int factor, int limit ){

Set<Integer> collect = new HashSet<Integer>();

}
return collect;
}

public static List<Integer> multiplesOf( int[] factors, int limit ){

List<Integer> collect = new ArrayList<Integer>();

for( int factor : factors ){


}
}
return collect;
}

public static Set<Integer> multiplesOf( int[] factors, int limit ){

Set<Integer> collect = new HashSet<Integer>();

for( int factor : factors ){


}
}
return collect;
}

Distinction

public boolean isGoodDeal( BigDecimal initialCosts,
BigDecimal runCosts ){

BigDecimal totalCost = initialCost.add( runCost );

BigDecimal oneP = totalCost.divide( new BigDecimal( 100 ) );

BigDecimal propRunCosts = wk.divide( oneP, 2, DOWN );

return ! propRunCosts.compareTo( new BigDecimal( 50 ) ) > 1;
}

Distinction



BigDecimal as Money

}

Distinction

BigDecimal as Percent



}

Distinction





}

What's the result 'type' of
combining 'Money' with 'Percent'

Distinction





}

Which combinations are allowed -
which not ?

Distinction

public boolean isGoodDeal( Money initialCosts, Money runCosts ){

Money totalCost = initialCosts.sum( runCosts );

Percent proportionRunCosts = totalCost.proportionOf( runCost )

return proportionRunCosts.isGreaterThan( Percent.FIFTY )
}

Single Responsibility Principle

Mental Distance
Mental Distance

... do you recognize the underlying concept ?

interface Stepper<T>{

public boolean isExhausted();

public void step();

public T getCurrent()
}


interface ElementSupplier<T>{

public boolean hasMoreElements();

T nextElement();
}


interface ElementConsumer{

public void observe( BigElement e );

public void calculate( AnotherElement e );

public void extract( YetAnotherElement );
}


interface ElementInspector{

public void inspect( BigElement e );

public void inspect( AnotherElement e );

public void inspect( YetAnotherElement );
}


interface ElementVisitor{

public void visit( BigElement e );

public void visit( AnotherElement e );

public void visit( YetAnotherElement );
}

Language

date.compareTo( otherDate ) < 0

vs.

date.isBefore( otherDate )

Verifiable Specifications
Stack stack = is(
new DescriptionOf <Stack>(){
public Stack isDescribedAs(){
Stack<String> stack = new Stack<String>();
stack.push( foo );
stack.push( bar );
return stack; } } );

it( "should contain foo" );
state( stack ).should( contain( foo ) );

it( "should contain bar" );
state( stack ).should( contain( bar ) );

it( "should return bar when calling pop the first time" );
state( stack.pop() ).should( returning( bar ) );

it( "should return foo when calling pop the second time" );
stack.pop();
state( stack.pop() ).should( returning( foo ) );

it( "should be empty after popping the two elements" );
stack.pop();
stack.pop();
state( stack ).should( be ( empty() ) );

Design by Contract
@Invariant( "this.size >= 0 and this.size <= this.capazity" )
public interface Stack { ... }
@Postcondition( "return > 0" )
public int getCapacity();

public int getSize();

@Precondition( "elem not null and this.size < this.capacity" )
@Postcondition( "elem == this.top and this.size == old:this.size + 1" )
public void push( Object elem );

@Postcondition( "this.top == old:this.top ) " )
public Object getTop();

@Postcondition(
"(old:this.size>0) ==> (return == old:this.top and this.size == old:this.size - 1)")
public Object pop();

...
}

Liskovsubtype of T, then objects of type T in a
''if S is a
Substitution Principle
program may be replaced with objects of type S
without altering any of the desirable properties''

Principle of least astonishment

...

void writeToFile( Output outout ){

openFile();

writeToFile( output );

}

void process{

input();

count++;

output();
}

Dependency Inversion Principle
declarative
vs
Intention Revealing Interfaces imperative

Functional Programming
Yagni Immutability
side effects

Expressiveness

Domain Driven Design
Consistence

If there are three things to keep in mind ...

… it's not only ''developers! developers! developers!'' ...

… but

Empathy!

Empathy!

Empathy!

Now stop hacking code
for machines

start writing programs
for humans

… and the rest will follow ...

Empathic Programming - How to write comprehensible code

Empathic Programming - How to write comprehensible code

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (15)

Similaire à Empathic Programming - How to write comprehensible code

Similaire à Empathic Programming - How to write comprehensible code (20)

Dernier

Dernier (20)

Empathic Programming - How to write comprehensible code