Development Guidelines

Development Guidelines

Daniel Olmedilla29 June 2007

June 29th, 2007 2Daniel Olmedilla

Outline

Introduction

Facts

Analysis and Design

Development

Test

Summary


IntroductionMotivation for these slides

At L3S We are creating a large amount of code Overlap among code being created Little reusability Bad development practices No feeling of team

Each one programs his part and no-one else checks it ever

Etc.


IntroductionProvocative Statement

Commonplace: “if enough monkeys were given typewriters and left to mess with them for long enough, one of them would type the complete works of Shakespeare”

There are two ways to write a computer program: understand the problem to be solved and the

programming system to be used; devise a strategy for solving the former using the latter; implement this – or

hammer on the keyboard until what you tried works the way you were asked for. [ http://www.chaos.org.uk/~eddy/when/2006/monkey.html ]


IntroductionBad Development Practices

Developed code is usable only for a paper No reusability, no understanding Lack of modularity Wrong design Lack of tolerance to failures No testing No traces Etc.

In summary(Almost) Impossible to use, re-use and

maintain


IntroductionDisclaimer

IMHO it is impossible to have a full SE methodology at L3S We are not a software development company These guidelines are a compromise

This is not an exhaustive list of guidelines

Although some things focus on Java, most of them are extendable to any other programming language

It is based on my observations and experience, therefore Take it only as informative Unless you work with me, in which case it is normative


IntroductionFacts to remember

Code may be reused (even by you) Team feeling: Not only you use what you develop

When you leave, others may take care of it If you are not available, others may have to work on it You don’t want to be the only one who can change it !!!

In the ideal world “refactoring does not exist” Do it right at first, otherwise, it takes you double time “More haste, less speed”

Following these practices increases the developing time? Wrong !!!! Coding is actually the shortest task It actually saves you time

- at debugging, testing, maintaining and new developments

Think ahead


Analysis and DesignMost valuable recommendation

Only one thing:

First think, then code


Analysis and DesignBe Practical

In many times it is not possible to have a full analysis and design phase but you should at least:

Make architecture diagrams (with the different modules)

Make UML class diagrams most of the boxes from the architecture diagram are

interfaces !

Possibly make activity and/or sequence diagrams Plan tests for each of the classes/modules with

“logic” Ideally the tests are created before you start to code


Analysis and DesignSimple example: Requirements

Create an application that receives keywords Checks against an index and returns a set of

hits Retrieves the hits from a database Returns the results


InvertedIndex

+String [] hits retrieve( String [] keywords )

SearchManager

+RDF results search( String [] keywords )

DBStore

+String [] results retrieve( String [] hits )

WebServer

+Message receive()

- index - database

- commChannel

Analysis and DesignSimple example: Diagrams (Wrong)

Web Service Server

Search Manager

Inveterted Index MySQL Database

What if we change to Postgresql?

What if we change to more expressive queries?

What if we want to use sockets?


Storage

+RDF results retrieve( URI [] hits )

SearchManager

+RDF results search( String query )

Index

+URI [] hits retrieve( String query )

CommunicationChannel

+Message receive()

RDFRepository

RDFStoreInvertedIndex

JDBCRDBMS

LuceneIndex FileSystem

WebServer

DBIndexDBStore

Sockets

Sesame

RMI

Jena

- index

- db

- database

- db- rdfDB

- commChannel

Analysis and DesignSimple example: Diagrams (Right)

Interface

Interface

InterfaceCommunication Interface

Search Manager

Index Interface Storage Interface

Reusable class


DevelopmentTry to understand (I)

No comments

Too long


DevelopmentTry to understand

Create a new function

Replace all that by “retrieveAccessibleMetad

ata(…)” and the whole “for” becomes clear at

first glance


DevelopmentSpecify and handle exceptions

void method (…){

try{do

something ;} catch

(Exception e){}

}

Don’t catch all with Exception, use

subclasses

Don’t leave it empty

Exceptions may pass through classes (that’s

the idea)

Raise different exceptions for different situations (not just one

for everything). Subclass it.

Don’t exit either


DevelopmentRestrict as much as possible

(Almost) Never use static variables and methods Do it only if you are really sure you cannot do it

without (e.g., Singleton) Rule of thumb: “If your static method needs to use a

class variable, most likely your method should not be static”

Use “public” only if needed Use class variables only if it cannot be done

with method variables only Etc.


DevelopmentMore programming guidelines (I)

Naming Organize in packages Give relevant names to classes, variables, constants

- Suffix with “I” if interface, suffix with Impl if implementing an interface, prefix with “Abstract” if abstract

- “Search” is a method name (not a class name). Use “SearchAgent”

Order matters E.g., use this order: constants, static vars, class vars,

constructors, init methods, extra methods, getters and setters, inner classes, etc…

Use constants (ideally no string or number should appear inside methods)

Even better, use configuration files (more on that later) Functions should be short

ideally around 15 lines maximum If a “for” or “while” statement has >5 lines, create a new

function


DevelopmentMore programming guidelines (II)

Your code should look nice too Indent your code No more than one statement per line Spaces Group statements If condition //newline// then action Etc.

And should be clear to understand Name “_var” your class variables and “var” the rest Constants all in uppercase Classes names: SearchAgent, InvertedIndex, … Methods names: searchForAttribute,

checkIfAvailable Enable all warnings in eclipse


DevelopmentMore programming guidelines (& III)

Use interfaces (also as returning classes) Use the most abstract interface E.g., Don’t use Vector, use Collection or otherwise List instead

Classes are units of function Same class can read and write on a file Same class should not give access to a database and fill the

database at the same time (different level of abstraction) Same class should not give access to a database and perform an

algorithm with the data Etc.

Use iterators (avoid “for” or “while” iterators) Abstract your datatypes (so it doesn’t matter how you

implement it) E.g., Matrix, Record, Document instead of using directly arrays

Apply design patterns

And many more things you, as computer scientist, find important


DevelopmentTeam Work & Project Management (I)

If you don’t know about CVS, read a tutorial before you use it

You may kill work from your colleagues If your project application is running, be sure that what you

commit does not break it E.g., running automatic JUnit tests (see later) That does not mean you don’t commit on the CVS

- Just use a “sandbox” folder- Ideally you should commit your code every day you worked on it

Many times not everything can be done at once Write your code iteratively (add features in new iterations)

- Error handling, documentation, etc.. ALWAYS at first iteration !! But write down in your code TODOs so you don’t forget

- Eclipse shows you all TODOs Or use bug tracking tools (highly recommended)

DevelopmentTeam Work & Project Management (& II)

Always Add a header like the following to any of your java classes

package org.policy.config;

import java.beans.BeanInfo;…

/** * * This class reads a configuration file and set up the system accordingly. * * $Id: Configurator.java,v 1.8 2007/05/15 20:48:14 DanielOlmedilla Exp $ * * Date: 05-Dec-2003 * * Last changed: $Date: 2007/05/15 20:48:14 $ * by $Author: DanielOlmedilla $ * * @author Ingo Brunkhorst and Daniel Olmedilla */public class Configurator{…}

Don’t change these entries.

Everything between “$” is set by the CVS

automatically



automatically



automatically

You can set it up in Eclipse so it is added automatically

in new classes


DevelopmentDebugging & Support


DevelopmentDebugging & Support: Logging

Ideally logging will let you find an error without the need to re-run your application again Logging is not temporal

If you create a log statement, it stays there forever Log values of variables

It will let you discover errors Use logging facilities

Different levels of logging: info, debug, warn, error “System.out.println” is forbidden

Logging is even more critical if Your application is used by remote users You use multiple threads

If well done, it partially serves as documentation Make it at the same time you code, don’t wait till the end


DevelopmentThe two kind of logging Traces

I am here

1

2

3

Ahhhhhhhhh

Entering function

Leaving function

1

2.2

It reaches here

Class initialized with sum = 20

Entering function multiply with args 3 and 5

Leaving function multiply with result 15

Database connection initialized with …

Calling database with query “select …”

Returning 7 results for database query “…”

ParsingException thrown with message …

Ignoring exception, continue with values …

Error calling function divide with 5 and 0

…


DevelopmentAdvance Configuration File: Benefits

Nothing is hardcoded Different configurations without touching code Different properties and values without touching code You force yourself to use interfaces Initialization is a bit slower, but running time is the

same Only what is needed is loaded

Possibility to generate different jar files- E.g., for mobile devices or PCs

It can be easily visualized (it helps as documentation)

Check www.L3S.de/~olmedilla/policy/doc/HOWTOs/how_to_use_the_Java_Configurator.html


DevelopmentConfiguration File Visualization


TestingJUnit Tests

Problem: We normally do not test what we develop Only run it manually a couple of times

if it does not fail, we are done (till someone complains)

if it fails, we check the run that made the failure- We do not run again the previous tests that worked

Not much to say here Create a JUnit class with several tests for each class Everytime you make a change, run all JUnit tests

automatically Ideally not only the ones from the class you changed,

but all tests


Conclusions

Anyone can program, even monkeys you are computer scientists !

you have to make a difference ou are supposed to think and to know about Software

Engineering

You are in a team, even if you program an application for yourself Your work can be used, reused, extended, etc… by your

colleagues Worse code because of making it fast does not save you time

“More haste, less speed” Time is therefore not an excuse

To think hurts , but it pays off


Questions?

[email protected] - http://www.L3S.de/~olmedilla/

Thanks!

Development Guidelines

Documents

Transcript of Development Guidelines