Programming Handbook

Transcription

1 Editor: Version: 1.0 Date: Abstract This document describes coding standards for Java language, which is used for implementation in Project Audio Jury. It also describes how to install and use the development tools that will be used in this project.

2 ii

3 PROJECT IDENTITY, Linköping Institute of Technology Department of Computer and Information Science (IDA) Project members Name Responsibility Telephone Per Andersson Document responsible (DOK) David Akhvlediani Implementation responsible (IMP) Robert Johansson Design responsible (DES) Lars Larsson Customer responsible (KUND) Johan Marnetoft Quality responsible (KVAL) Gustav Rosèn Project leader (PL) Mikael Svärd Test responsible (TEST) Christoffer Årstrand System responsible (SYS) Mailing list for the entire group Homepage Customer Sony Ericsson Mobile Communications AB Customer contact Wanqing Shi, Sonia Sangari, Mentor Mustapha Skhiri, Course responsible Uwe Assman, PROJECT IDENTITY iii

4 iv

5 DOCUMENT HISTORY Date Version Name Change Christoffer Årstrand The making of this document Per Andersson Just updating to v1.0 DOCUMENT HISTORY v

6 vi DOCUMENT HISTORY

7 1 Naming Conventions Packages Classes and Interfaces Classes Exception Classes Interfaces Methods General Methods Getters and Setters Factory methods Converter methods Debug methods Static methods Variables General variables Temporary variables Component variables Constants Formatting Indentation Spacing Spacing Class member ordering File format Maximum Line Length Parentheses Declarations Number Per Line Initialization Placement Class and Interface Declarations Statements Simple Statements Compound Statements return Statements if, if-else, if else-if else Statements for Statements while Statements do-while Statements switch Statements Table of contents vii

8 4.9 try-catch Statements Commenting Implementation Comment Format C Style Comments Single line Comments Documentation Comments Writing JavaDoc comments Format of JavaDoc comment Descriptions Tags Example Development Tools Setup Download Install Fix But I am at IDA CVS Overview Fundamentals The client The server Sun ONE Studio 4.0 ce Overview Using the IDE viii Table of contents

9 1 Naming Conventions 1.1 Packages Package names should be written in all-lowercase ASCII letters. 1.2 Classes and Interfaces Classes Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. class Customer class OrderItem Exception Classes Name of exception classes should be ended with Exception. class RuntimeException Interfaces The Java convention is to name interfaces using mixed case with the first letter of each word capitalized. Use a descriptive name for the interface. Interface Runnable Interface Cloneable 1.3 Methods General Methods Use a full English description with mixed case with the first letter of any non-initial word capitalized. Make the first word of a method a strong active verb. Color mixcolors(colorlist list); Getters and Setters Getters and Setters for object of type X should be written as "X getx()" and "void setx( X value)" accordingly. Boolean getters should use "is" as a prefix. Chapter 1: Naming Conventions 1

10 Color getcolor(); void setcolor(color c); boolean iswhite(color c); Factory methods Factory methods for object of type X should be written as "X NewX()". public class WidgetFactory { static Button NewButton(int abuttontype); static ListBox NewListBox(); ; Converter methods Converter method that returns object of type X should be as "X tox(...)" Color tocolor(rgb rgb); Debug methods Methods for debug-only implementation should begin with "debug". void debugdumptoscreen(); Static methods Static methods should begin with a capital letter with each subsequent new word in uppercase, and subsequent letters in each word in lower case. static void SomeClassMethod(int avalue); 1.4 Variables Variables should not start with underscore _ or dollar sign $ characters General variables Use a full English descriptor to name fields. Use plural names for collections of arrays and vectors. Name should be short yet meaningful. The choice of a variable name should be mnemonic - that is, designed to indicate to the casual observer the intent of use. String firstname; float mywidth; 2 Chapter 1: Naming Conventions

11 Vector orderitems; Temporary variables One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i,j,k,m and n for integers; c and d for characters; e for exceptions; in, out, inout for streams Component variables Prefix component variables with component mnemonic. btnok lblcustomer mnufile edtcustname cmbstreets 1.5 Constants Values that do not change are implemented as static final fields of classes. Use only uppercase letters in the names of final variables, with words separated by underscores. This will make these constants stand out in a program. static final int MINIMUM_BALANCE = 1000; Chapter 1: Naming Conventions 3

12 4 Chapter 1: Naming Conventions

13 2 Formatting 2.1 Indentation All indents are four spaces. Matching braces are always in the same column as their construct. All indenting is done with spaces, not tabs. Reasoning: All programs work well with spaces. Most programs will mix tabs and spaces so that some lines are indented with spaces and some with tabs. If your tabbing is set to four and you share a file with someone that has tabbing set to 8, everything comes out goofy. All if, while and for statements must use braces even if they control just one statement. Reasoning: Consistency is easier to read. Plus, less editing is involved if lines of code are added or removed. if(superhero == thetick) Sytem.out.println("Spoon!"); // NO! if ( superhero == thetick ) { // YES! System.out.println("Spoon!"); 2.2 Spacing All identifiers are surrounded with whitespace. int thetick=5; int thetick = 5; // NO! // YES! if (thetick==5) // NO! if ( thetick == 5 ) // YES! There are few exceptions to these rule: foo (i) // NO! foo( i ); // YES! Chapter 2: Formatting 5

14 start (); // NO! start(); // YES! args [0]; // NO! args[ 0 ]; // YES! ++ count; // NO! ++count; // YES! (MyClass) v.get(3); // NO! ( MyClass )v.get(3); // NO! (MyClass)v.get( 3 ); // YES 2.3 Spacing Use the occasional blank line within methods to break up related chunks of code. Use one or two blank lines between all methods. 2.4 Class member ordering class Order { // Constants // Instance variables // Static initializers // Main method // Static class methods // Instance initializers // Constructor methods // Private methods // Protected methods // Accessor methods // Instance methods // Debugging methods 6 Chapter 2: Formatting

15 2.5 File format "package" (if used) must always come first. "import"s are next. Any non javadoc comments are next. Any javadoc class documentation is next. The class is last. Only one class per file (excepting inner classes). package misc; import java.io.*; import java.net.*; /** this class does cool Joe Programmer */ class SpaceMonkey { Maximum Line Length Most of your code should be under 80 characters per line. If your code starts to get indented way to the right, consider breaking your code into more methods. 2.7 Parentheses Parentheses should be used in expressions not only to specify order of precedence, but also to help simplify the expression. When in doubt, parenthesize. Chapter 2: Formatting 7

16 8 Chapter 2: Formatting

17 3 Declarations 3.1 Number Per Line One declaration per line is recommended since it encourages commenting. In other words, int level; // indentation level int size; // size of table is preferred over int level, size; Do not put different types on the same line. int foo, fooarray[ ]; // WRONG 3.2 Initialization Try to initialize local variables where they are declared. The only reason not to initialize a variable where it s declared is if the initial value depends on some computation occurring first. 3.3 Placement Put declarations only at the beginning of blocks. (A block is any code surrounded by curly braces "{" and "". Don t wait to declare variables until their first use; it can confuse the unwary programmer and hamper code portability within the scope. void mymethod() { int int1 = 0; // beginning of method block if ( condition ) { int int2 = 0; // beginning of "if" block... Chapter 3: Declarations 9

18 The one exception to the rule is indexes of for loops, which in Java can be declared in the for statement: for ( int i = 0; i < maxloops; i++ ) {... Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block: int count;... mymethod( ) { if ( condition ) { int count; // AVOID! Class and Interface Declarations When coding Java classes and interfaces, the following formatting rules should be followed: - No space between a method name and parenthesis "(" starting its parameter list - Open brace "{" appears at the end of the same line as the declaration statement - Closing brace ")" start a line by itself indented to match its corresponding opening statement, except when it is a null statement, the "" should appear immediately after the "{" class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; int emptymethod() { - Methods are separated by a blank line 10 Chapter 3: Declarations

19 4 Statements 4.1 Simple Statements Each line should contain at most one statement. argv++; // Correct rgc++; // Correct argv++; argc--; // AVOID! 4.2 Compound Statements Compound statements are statements that contain lists of statements enclosed in braces "{ statements ". See the following sections for examples. -The enclosed statements should be indented one more level than the compound statement. -The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement. -Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces. 4.3 return Statements A return statement with a value should not use parentheses unless they make the return value more obvious in some way. return; return mydisk.size(); return (size? size : defaultsize); 4.4 if, if-else, if else-if else Statements The if-else class of statements should have the following form: if ( condition ) { statements; Chapter 4: Statements 11

20 if ( condition ) { statements; else { statements; if ( condition ) { statements; else if ( condition ) { statements; else { statements; Note: if statements always use braces {. Avoid the following errorprone form: if ( condition ) //AVOID! THIS OMITS THE BRACES {! statement; 4.5 for Statements A for statement should have the following form: for ( initialization; condition; update ) { statements; An empty for statement (one in which all the work is done in the initialization, condition, and update clauses) should have the following form: for ( initialization; condition; update ); When using the comma operator in the initialization or update clause of a for statement, avoid the complexity of using more than three variables. If needed, use separate statements before the for loop (for the initialization clause) or at the end of the loop (for the update clause). 12 Chapter 4: Statements

21 4.6 while Statements A while statement should have the following form: while ( condition ) { statements; An empty while statement should have the following form: while ( condition ); 4.7 do-while Statements A do-while statement should have the following form: do { statements; while ( condition ); 4.8 switch Statements A switch statement should have the following form: switch ( condition ) { case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; Chapter 4: Statements 13

22 Every time a case falls through (doesn t include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment. Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added. 4.9 try-catch Statements A try-catch statement should have the following format: try { statements; catch (Exceptionality e) { statements; A try-catch statement may also be followed by finally, which executes regardless of whether or not the try block has completed successfully. try { statements; catch (ExceptionClass e) { statements; finally { statements; 14 Chapter 4: Statements

23 5 Commenting Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments ( known as doc comments ) are Java-only, and are delimited by /**...*/. Doc comments can be extracted to HTML files using the javadoc tool. Implementation comments are means for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective to be read by developers who might not necessarily have the source code at hand. Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program. For example, information about how the corresponding package is built or in what directory it resides should not be included as a comment. Discussion of nontrivial or non obvious design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. It is too easy for redundant comments to get out of date. In general, avoid any comments that are likely to get out of date as the code evolves. Note: The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer. Comments should not be enclosed in large boxes drawn with asterisks or other characters. Comments should never include special characters such as form-feed and backspace. 5.1 Implementation Comment Format C Style Comments C style comments start with /* and end with */. Use to document lines of code that are no longer applicable, but that may be required later on, or to temporarily turn the code off while debugging. /* This code is temporarily disabled and replaced by a new method of calculating ASD. Performance tests will reveal which method is the best. */... (source code) Chapter 5: Commenting 15

24 5.1.2 Single line Comments Single line comments start with // and go to the end of the line. Use internally within member functions to document business logic, sections of code, and declarations of temporary variables. Example 1: // Strategy: // 1. Find the node // 2. Clone it Example 2: int level; // indentation level int size; // size of table Example 3: void mymethod() { int int1 = 0; // beginning of method block if ( condition ) { int int2 = 0; // beginning of "if" block Documentation Comments Writing JavaDoc comments JavaDoc comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters /**...*, with one comment per class, interface, or member. This comment should appear just before the declaration. /** * The Example class provides... */ public class Example {... If you need to give information about a class, interface, variable, or method that isn t appropriate for documentation, use an implementation comments. 16 Chapter 5: Commenting

25 JavaDoc comments should not be positioned inside a method or constructor definition block, because Java associates documentation comments with the first declaration after the comment Format of JavaDoc comment If a JavaDoc comment can fit on one line, the format to be used is like this: /** Used to mart spots */ int x; if a JavaDoc comment spans more than one line, the format to be used is like this: / ** * Returns an Image object that can then be painted on * the screen.the url argument must specify an absolute * {@link URL. The name argument is a specifier that is * relative to the url argument. * <p> * This method always returns immediately, whether or not * the image exists. * url an absolute URL giving the base location nm the relative location of the image the image at the specified URL Image */ public Image getimage(url url, String nm ) {... Notes: - Each line above is indented to align the code below the comment. - The first line contains the begin-comment delimiter (/** ). - Write the first sentence as a short summary of the method, as JavaDoc automatically places it in the method summary table (and index ). - Notice the inline tag {@link URL, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags. Chapter 5: Commenting 17

26 - If you have more than on paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag, as shown. - Insert a blank comment line between the description and the list of tags, as shown. - The first line that begins with an "@" character ends the description. There is only one description block per doc comment, you cannot continue the description following block tags - The last line contains the end-comment delimiter (*/). - Limit any doc-comments line to 80 characters Descriptions The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item. This means the first sentence of each member, class, interface or package description. The JavaDoc tool copies the first sentence to the appropriate member, class/interface or package summary. This makes it important to write crisp and informative initial sentences that can stand on their own. You can avoid retyping doc comments by being aware of how the JavaDoc tool duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases. - When a method in a class overrides a method in a superclass - When a method in an interface overrides a method in a superinterface - When a method in a class implements a method in an interface In all three of these cases, if the method m() contains no doc comments or tags, the JavaDoc tool will also copy the text of the method it is overriding or implementing. So if the documentation of the overridden method is sufficient, you do not need to add documentation for m() Tags Include tags in the following (classes and interfaces only, (classes and interfaces only, (methods and constructors @deprecated 18 Chapter 5: Commenting

27 name-text By default author information is not included when generating the API specification, and so it is seen only by those viewing the source code. Author information can be included in the generated documentation when the -author option is used. tags should be listed in chronological order, with the creator of the class listed at the Herb Jellinek version-text Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. The text has no special internal 1.5, 07/12/99 parameter-name description Adds a parameter to the "Parameters" section. The description may be continued on the next line. tag is followed by the name of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. An exception is made for the int, where the data type is usually omitted. Additional space can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash. Parameter names are lowercase. The data type start with a lowercase letter to indicate an object rather than a class. The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it. tag is required for every parameter, even when the descriptions is obvious. tags should be listed in argument-declaration order. This makes it easier to visually match the list to the ch the character to be observer the image observer to be notified Chapter 5: Commenting 19

28 description Adds a "Return" section with the description text. This text should describe the return type and permissible range of values. for methods that return void and for constructors; include it for all other methods, even if its content is entirely redundant with the method a Hashtable of Points class-name description Add a "Throws" subheading to the generated documentation, with the class-name and descriptor text. The class-name is the name of the exception that may be thrown by the method. tag should be included for any checked exceptions (declared in the throws IOException If an in/out exception occurred reference Add a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number tags, which are all grouped under the same heading. tag has three variations; the third form below is the most common. For inserting an in-line link within a sentence to a package, class or member, use "string" Add a text entry for string. No link is generated. The string is a book or other reference to information not available by "The Java Programming <a href="url#value"> label </a> Add a link as defined by URL#value. The URL#value is a relative or absolute <a href="spec.html#section"> Java Spec package.class#member label Adds a link, with visible text label, that points to the documentation for the specified name that is referenced. The label is optional; if omitted, the name appears instead as the visible String#equals(Object) equals (refers to the equals method in the String class) 20 Chapter 5: Commenting

29 since-text Add a "Since" heading with the specified since-text to the generated documentation. The text has no special internal structure. This tag means that this change or feature has existed since the software release specified by the 1.5 field-description include exclude Used in the doc comment for a default serializable field. An optional field-description should explain the meaning of the field and list the acceptable values. If needed, the description can span multiple lines. The include and exclude arguments identify whether a class or package should be included or excluded from the serialized form page. They work as follows: - A public or protected class that implements Serializable is included unless that class (or its package) is exclude - A private or package-private class that implements Serializable is excluded unless that class (or its package ) is include The at class level at a package level. field-name field-type field-description Documents an ObjectStreamField component of a Searializable class serialpersistentfields member. tag should be user for each ObjectStreamField path String data-description The data-description documents the types and order of data in the serialized form. Specifically, this data includes the optional data written by the writeobject method and all data( including base classes ) written by the Externalizable.writeExternal method. tag can be used in the doc comment for the writeobject, readobject, writeexternal and readexternal Default fields followed by separator character Chapter 5: Commenting 21

30 deprecated-text Adds a comment indicating that this API should no longer be As of JDK 1.1, replaced by {@link #set Bounds(int,int) Syntax: package.class#member label Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class. This tag is very similar -- both require the same references and accept exactly the same syntax for package.class#member and label. The main difference is that {@link generates an in-line link rather than placing the link in the "See Also" section. Also, the {@link tag begins and ends with curly braces. Use the {@link #getcomponentat(int,int)getcomponentat method Syntax: When used in a static field comment, displays the value of the constant. 22 Chapter 5: Commenting

31 6 Example /* /03/18 * * Copyright (c) Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, * All Rights Reserved. * */ package java.blah; import java.blah.blahdy.blahblah; /** * Class description goes here. * Mar 1999 Firstname Lastname */ public class Blah extends SomeClass { /* A class implementation comment can go here. */ /** classvar1 documentation comment */ public static int classvar1; /** * classvar2 documentation comment that happens to be * more than one line long */ private static Object classvar2; /** instancevar1 documentation comment */ public Object instancevar1; Chapter 6: Example 23

32 /** instancevar2 documentation comment */ protected int instancevar2; /** instancevar3 documentation comment */ private Object[] instancevar3; /** *... constructor Blah documentation comment... */ public Blah() { //...implementation goes here... /** *... method dosomething documentation comment... */ public void dosomething() { //...implementation goes here... /** *...method dosomethingelse doc comment... someparam description */ public void dosomethingelse(object someparam) { //...implementation goes here Chapter 6: Example

33 7 Development Tools This chapter will describe how to install and use the development tools that will be used in this project (Audio Jury). It is recommended that you run the tools described in this chapter on a relatively fast PC that you have control over. The machines at IDA are a bit to slow and a bit to restrictive. If you still want to run it at IDA, jump to the section "But I am at IDA". Because of this matter, the text in the rest of this chapter will assume that you are working in a windows environment and have full access to the machine. Large parts of this document is still useful though if you are running some other platform such as Solaris or Linux, because all the programs described are available for free on most major platforms. 7.1 Setup Note: Note: Download The first thing you need to do is to download the software needed. This means downloading the development system (Sun ONE Studio 4.0 ce) from Sun, and a CVS package called TortoiseCVS (which also includes SSH). Note: Throughout the rest of the document CVS and SSH will usually be referred to "cvs" and "ssh" to promote readability. If you already got a working cvs and ssh installation on your system you might not need to download TortoiseCVS. To check this type in cvs (ssh)ina terminal window. If the system finds and runs something then you probably got a working cvs (ssh) installation. Even if you got a cvs client installed that does not neccesarely mean that it is compatible with the type of connection that we use with the cvs server. One symptom is that the client responds with an ":ext: authication not suported". If that, or any other strange errors occurs, try installing TortoiseCVS in addition to your current cvs client. TortoiseCVS has the possibility to integrate itself in the windows explorer. If this is not wanted then deselect that when installing, or chose another cvs package. The rest of this chapter will assume that you installed TortoiseCVS but not necessarily with the explorer integration TortoiseCVS Go to the web page at and download the latest stable package. As of now that is version Sun ONE Studio 4.0 ce Go to the web page at and scroll down a bit until you find "Community Edition". There is two Chapter 7: Development Tools 25

34 downloads, one that only contains the development tool, and one that is bundled with a Java SDK (J2SE as of now). Download the one that is appropriate for your system, if unsure select the bundled version. This download is quite bit (in the proximity of 100MB) so you might want to start the download before you continue reading this document Install Install is quite straight forward since both programs has install wizards in them. Just run the files you downloaded and off you go. Note in what directory you install TortoiseCVS Fix Note: If you didn t install TortoiseCVS because you could run the tests in the section Download successfully then you can ignore the rest of this section. After the installation there is some thing to fix. Sun ONE Studio will assume that there are two executable files, one is ssh.exe and the other one is cvs.exe. This will not be the case if you just downloaded and installed the cvs package, since the files it installed is most likely not in your systems search path. To rectify this you can do as follows. Open the directory where you installed TortoiseCVS, usually c:\program\tortoisecvs or c:\program files\tortoisecvs. Copy the file TortoisePlink.exe to the root of you system drive (c:\ or somewhere else on you system that is included in the path, for example your windows directory. Rename the copy of TortoisePling.exe to ssh.exe. Open a terminal window and type c: followed by an enter. Type in cd \ followed by an enter. Type ssh followed by an enter. If the system runs the programs (they will list a table of parameters) you are OK. If not contact you Systemsanta for help But I am at IDA The PC machines on IDA are more or less of no use for this project, but the Sun machines can be used to some extent for implementation. Since they are running Solaris the cvs and ssh clients are automatically available, well not automatically but they are there by default. Sun ONE Studio 4.0 can not be installed though, but there is and older version that can be used. What you need to do is add the module for it. This can be done by typing module add prog/forte4j-ce/3.0 in a terminal window follow by an enter. If you want the program to be available every time you log in, enter it again but change the add to initadd. Note: This is already prepared for use in the pum account, but it is unsure what will happen if several user run it at the same time, so using it might me hazardous. You can now type forte4j (do not add a & after the name!) in a terminal window to start the program. You can install and run it on your own user account, but be aware that when it starts for the first time it will create several well over 1MB in total in your home directory. This might bring you over quota since the basic 26 Chapter 7: Development Tools

35 quota is a lousy 5MB. To check your quota type quota -v in a terminal window. To sum it up, it is probably better, safer and faster if you install and run the program on your home computer. 7.2 CVS Overview CVS stands for Concurrent Versions System and is a powerful (and free) tool for version control of computer source code and other form of non binary data. This is done in an ordered fashion and enables multiple developers to work on the same set of files (even the same file!) at the same time. For more in depth information about CVS check out and the sort of official manual called "the Cederqvist" that can be found there in there in the Manual section. There is two main modes that CVS can work in, either with a server or without. If you go the serverless way all the files are kept in a special folder somewhere that all developers can access locally or remote in one way or another. If you use a server all the files are kept on the server. We will use the later with a server located at and run by Lysator Academic Computer Society (Lysator for short). They have a web page with more information about them at Fundamentals To fully teach all the tricks and features there is to cvs is to big of a challenge for this document, we won t use most of them anyway. But before you can get a basic idea of how things work you need to know the terms of which they are called. Bellow is a small list of terms and their respective meaning and use. It is also recommended that you read the first chapter (Overview) in the Cederqvist Working directory This is a local directory where you keep your working copies of the files that are under version control by the cvs system Repository This is the directory where all the files under version control are saved. This can be a server or on a local or remote disc. Never, never ever, modify this directory directly if you are not entirely sure on what you are doing! Module The repository contains a number of modules that contain any number of files or directories Import To add a module to the repository you need to first import it into the reposatory. This is done via the import command. Chapter 7: Development Tools 27

36 Add The module contains a list of which files are under version control. To add a file to that list you must first add the file to the that module. After you done the add you must commit (se below) the file for it to be stored on in the repository. Remember one important thing: Once a file has been added, there is no way to completely remove it again! Therefore, do not add things if you don t need to and make sure that the filename is 100% correct Checkout This command is used to retrieve a complete module with the latest versions of the files kept within. It will create a new directory in you working directory with the same name as the module you retrieved. You are now free to edit and save those files as you wish. But do not mess around with the files in the subdirectory called CVS! Commit If you have done any changes to a file that you want to permanently save then you commit that work. This will update the files in the repository so that it now reflects the changes you made. This will make the changes available to anyone using the same repository, but more importantly, you can now always back up to that version of the file, even if you later make some mistake (like deleting the file or destroying functionality). You can not commit a file that hasn t been added to a module (by import or the add command). So there is no risk that you commit trash files (like compiled and temporary files) into the repository when you commit Update This command will synchronize the files in your working directory (or rather module) with the ones in the repository. No changes will be sent to the server, but your working directory will updated with the latest versions (and new files if there are any) from the repository. If there is a conflict (se below) between the version in the repository and your local files, then they local version of the files will be left intact. It is recommended to always update before you start working, so you do not do any work on old versions of the files! Merge & Conflicts When you change a file locally there is no way to tell if someone else has changed the very same file in his working directory. If he then commits his version of the file before you to the repository there can be a conflict. This scenario is often not allowed with other software (only one person can check out and modified a file at a time), but this is one of the biggest strengths of CVS! Lets say you check out and work on version 7 of a file. So does someone else, and he commits his work to the repository. The version in the repository is now higher then the file you once checked out and started working on, lets say 8. When you finnish your work you commit the file. The CVS system now compare your file with the stored version 7 and notes the changes you made. It also notice that version 7 is no longer the latest ver- 28 Chapter 7: Development Tools

37 sion. What it then does is that it tries to apply your changes to version 8, it merges your file with the one in the repository and puts the result in your working directory. If your and the other developer changed the file in different places there is no problem doing this, otherwise there will be a conflict, that is the CVS system does not know which version of the changes it should keep. If that is the case it will merge your version of the file with the one on the server and mark it up so you can see and resolve the conflict by hand. Even if there isn t a conflict as a result of a merge it is good to check that the merged file work as intended, this is why the repository isn t changed if the commit resulted in a merge. The file you got back is now marked as a modified version 8. So after you check the file you got back (and fix the conflicts, if any) you can commit it again, and the changes will be recorded in the repository and the version bumped to 9. That is if no one has commit any more work after your last attempt to commit The client The client is simply a little executable binary file by the name of cvs. You can use this binary to checkout, commit and all the other stuff by a command line. But in our project all this functionality will integrated into the IDE (Integrated Development Environment), in this case Sun ONE Studio. Note: The server The server is located and operated by Lysator Academic Computer Society (Lysator for short). This server contains lots of repositories, including a one called pum6_test that is used to test CVS and another called AudioJury that will contain all our official source code. To access these two repositorys and retrive the contents from them you will need a login and password. Contact the Systemsanta and he will add you to the list of approved users. The name of the modules will be decided on later. If you want to view what files there is in a repository on the cvs server you can go to the page and select pum6_test in the drop down box named "Project Root" and hit Go. The section under the drop down box will then update with the different modules that exist in the repository. You can click on them to show the contents of them and also view individual files. This feature can be toggled by the administrator of a project (the Systemsanta in this case), and the default is off. That is why you do not see AudioJury in the list. The contents of the cvs server is backed up regular at relatively short intervals. This is done by Lysator and hence it is nothing we need to worry about. This and the fact that the cvs system never allows the deleting of a file in a repository (you can only mark it as deleted) means that the risk of data loss is about as low as it gets. 7.3 Sun ONE Studio 4.0 ce Overview The main IDE (Integrated Development Environment) that we will use for the implementation of the project is Sun ONE Studio 4.0 ce. The "ce" stands for Community Edition which in turn stands for "free". That is that there is Chapter 7: Development Tools 29

38 Note: no licence fee to be paid for using this software in our project. This and the fact that it incorporates cvs support is the reason that it was chosen as the IDE for the project. Sun ONE Studio is the successor of Suns previous free IDE called Forte. There are some versions of Forte available on IDA s Sun machines. For more information about that, jump back to the section "I am at IDA" earlier in this chapter. Sun ONE Studio 4.0 ce will be referred to as the IDE in the rest of this chapter. The IDE and Forte ce 3.0 looks mostly identical and will probably be compatible in most cases. The cvs functions also work the same way. How ever, this is not true for Forte 2.0 and 1.0 which is also available on IDA. They will not work with the cvs server without a helping hand and should be avoided. Now start up the IDE and lets take a look at some of the main components Introducing the GUI There are several windows that make up the IDE. Most of them come and go as you switch between different modes of work (editing your stuff, running it, and so on). The main toolbar will always stay though, and it is by this toolbar that you switch between the different modes. If you look at the bottom left of the toolbar there is some tabs named Editing, GUI Editing, Running and Debugging. By clicking on these tabs you change the mode and the look of the IDE The Explorer Note: The explorer is located on the far left when you are in Editing or GUI Editing modes. This window is a multipurpose window, if you look at the bottom there are four tabs, the one that we are interested at the moment is tab labled Filesystem. When you are in the Filesystem mode of the Explorer the window shows you the files and directories that you have can edit at the moment. You can add stuff by right clicking on the text Filesystem, select Mount and chose what you want to mount. If you mount a Local Directory that directory will be shown as a new item under Filesystems in the window. You can expand the directory by clicking on the handle icon directly on the left of the name of it. It will then expand and show a list of it contents. To edit anything, just double click on it or right click to get a wider selection of choices. To unmount a directory, just right click on its name and select Unmount Filsystem. There is an extremely important thing that you must know about the Explorer in the Filesystems mode. The mounting really mounts the directory as it would on a Unix machine. That means that if you delete something from the explorer in this mode you also delete it from the real filesystem! Always keep that in mind when working. To create something in the directory you mounted simply right click on it and select New. The files will be created in the directory that you mounted. 30 Chapter 7: Development Tools

39 Mounting a CVS filesystem One of the best features of the IDE is that is integrates support for cvs, both with and without a server. You simply mount a module in a repository as you would mount a normal directory. To test this feature lets mount the module forte1 in the pum6_test repository on the cvs server we are going to use for the project. Note: Note: To do this exercise you must have received an from the Systemsanta with an user name and password for the cvs server at Lysator. If this is not the case, contact the Systemsanta. To select a directory in a file browser from within the IDE you must be in the parent directory when you press OK. Right click on Filesystems and select Mount->Version Control->CVS. Select a local working directory on your system. This is where the local copies of the files from the cvs server will be kept. I suggest you create a new empty directory and select it. Click on the button labeled Next. The system now prompt you for something called a relative mount point. For now just select the working directory and click Next. The following dialog contains a lot of fields to fill in. First select External as the Connection Method. Enter ssh in the field CVS_RSH. Enter cvs.lysator.liu.se in the field Server Name. Enter your user name for the cvs server in field User Name. This user name is usually _cvs_xxxxxyyy where xxxxxyyy is you user name on the IDA account. Select which Repository you want to use. The format on Lysator s cvs server is /cvsroot/name_of_repository. In our case it s /cvsroot/pum6_test. (Do not include the dot.) The CVSROOT should read :ext:sername@cvs.lysator.liu.se:/cvsroot/pum6_test. If it doesn t check the steps above for any errors. If or when it does click Next. If the IDE gives you a warning about public key atuhentication, just click Close. Now it is time to fill in where the cvs client can be found on your system. If you are at IDA or got a cvs client somewhere in the systems search path, just fill in cvs as the CVS Executable and click Next. Otherwise click on the Browse button and locate the directory where you installed TortoiseCVS previously in this chapter. Select the file cvs.exe in that directory and close the dialog. Click on Next. Skip the next page by clicking Finish. The IDE might prompt you for your password for the cvs server. This password will not be stored locally so it will ask you for it again later. Sometimes you need to enter your password several times in a row, this is normal. Note: The Solaris version Forte does not present a dialog when it want you to enter your password. Instead it will output the request to the terminal window in which you started Forte! That means that you should never start Forte as a background work (i.e. with a & after the filename) since this will mess up the password system. To Chapter 7: Development Tools 31

40 enter your password simply enter it into that terminal window and press enter, you will not see what you enter. If you see what you enter Forte is not prompting you for your password! Sometimes Forte prompts you for the password several times in a row. To solve this just enter your password, press enter, type it again, press enter, and so on until your keystrokes starts to appear in the terminal window. The cvs repository is now mounted, but we still need to mount a module to see any files. To do this right click on the icon for the mounted cvs file system and select CVS->Check Out. This will prompt you with another dialog to fill in. Simply enter the name of the module in the field named Module(s). The name of the module we want to add in this exercise is forte1 (that is the word forte follow by the number 1) and then press OK. Now expand the mounted cvs filesystem and then expand the directory forte1. You should now see the classes that exists in the module (and java package in this case) forte Using CVS commands Previously in this chapter was a listing of some fundamental concepts behind cvs. All but the last was also the name of the operation that you do to a set of files under cvs control. In this exercise we will edit one of the files and then commit the work for the rest of the world (or at least development team) to see. Expand the cvs filesystem so you see at least the level below forte1. Double click on the dialog you want to change. The IDE now switches into GUI Editing mode. If not, switch manually by selecting the appropriate tab in the toolbar. Change something! Add a button, move something around. Be create. Save the file by selection File->Save in the toolbar. Notice how the label of the class name in the explorer updates to reflect that the class has been changed locally. Switch back into Editing mode to clear away some clutter. Right click on the class name and select CVS->Commit. The IDE will now prompt you for a short message that describes what has changed, why it changed, that sort of thing. This message will be stored on the cvs server in conjunction with the version of the class you just committed. Keep it short but be descriptive. The IDE will probably ask for your password again a couple of times. If everything went OK (there was no conflict or merge) the label on the class should change into Up-to-date and the new version of the class. To add a new class to the module (and also a java package in this case), right click on the label for forte1 and select New->GUI Forms->JDialog (as an example). Select a name for it and hit Finish. Notice how the new class gets added under forte1. Also notice that the label for it states Local. That means that it is still a local file and not in the repository. Lets add it to the repository under the module forte1! 32 Chapter 7: Development Tools