Development Guidelines

1. Development Guidelines Daniel Olmedilla 29 June 2007

2. Outline • Introduction • Facts • Analysis and Design • Development • Test • Summary

3. 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.

4. 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 ]

5. 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

6. 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 

7. 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

8. Analysis and DesignMost valuable recommendation • Only one thing: • First think, then code

9. 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

10. 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

11. Analysis and DesignSimple example: Diagrams (Wrong) What if we want to use sockets? What if we change to more expressive queries? What if we change to Postgresql?

12. Analysis and DesignSimple example: Diagrams (Right) Interface Interface Interface Reusable class

13. DevelopmentTry to understand (I) No comments Too long

14. DevelopmentTry to understand Create a new function Replace all that by “retrieveAccessibleMetadata(…)” and the whole “for” becomes clear at first glance

15. DevelopmentSpecify and handle exceptions Exceptions may pass through classes (that’s the idea) • void method (…){ try{ do something ; } catch (Exception e) {}} Raise different exceptions for different situations (not just one for everything). Subclass it. Don’t catch all with Exception, use subclasses Don’t leave it empty Don’t exit either

16. 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.

17. 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

18. 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

19. 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

20. 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)

21. 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; • … • /** • * <p> • * This class reads a configuration file and set up the system accordingly. • * </p><p> • * $Id: Configurator.java,v 1.8 2007/05/15 20:48:14 DanielOlmedilla Exp $ • * <br/> • * Date: 05-Dec-2003 • * <br/> • * Last changed: $Date: 2007/05/15 20:48:14 $ • * by $Author: DanielOlmedilla $ • * </p> • * @author Ingo Brunkhorst and Daniel Olmedilla • */ • public class Configurator • { • … • } You can set it up in Eclipse so it is added automatically in new classes Don’t change these entries. Everything between “$” is set by the CVS automatically Don’t change these entries. Everything between “$” is set by the CVS automatically Don’t change these entries. Everything between “$” is set by the CVS automatically

22. DevelopmentDebugging & Support

23. 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

24. 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 … DevelopmentThe two kind of logging Traces

25. 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

26. DevelopmentConfiguration File Visualization

27. 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

28. 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

29. Thanks! Questions? olmedilla@L3S.de - http://www.L3S.de/~olmedilla/