1 Introduction

1.1 Scope

The aim of this project is to create an extension for the BlueJ IDE that will allow Java source code formatting. The goal of this product is to beautify and increase the readability of source code through an easy and intuitive interface in the BlueJ IDE. It is needed especially for beginner programmers and students with specific formatting requirements. The product must be flexible to accommodate different formatting preferences.

1.2 Product Features

This project will provide the user with a number of features for formatting their source code within the BlueJ IDE:

The user will be able to format a single or multiple Java source files.
The user will be able to customize the options for formatting the code including Indentation, Braces Style, Whitespace, Wrapping, and Blank Lines.
The user will be able to save and load customized formatting configurations.

1.3 User Characteristics

The intended users for this product are introductory programmers and computer science students. These users will be unfamiliar with proper coding styles or will have different professors that have different style guidelines. These users will probably use this product on projects composed of only a few files so ease of use is desired over high performance and scalability.

1.4 Constraints

The project must be written in Java.

1.5 Assumptions and Dependencies

The project must work with the BlueJ IDE and Java. We are assuming that the formatter will mostly be used on a small scale and not needed to format hundreds of files at once.

2 Functional Requirements

2.1 General Requirements

2.1.1 The user will be able to format compilable source code that successfully compiles.
2.2.2 The user will have the ability to format single or multiple source code file(s).
2.2.3 The user can format source code from the right click menu.
2.2.4 The user will have ability to restore file to its state before the most recent format was executed. This will not be available after the formatted file has been edited.
2.2.5 The user will be able to customize their formatting conventions from a GUI interface.
2.2.6 The user will have access to Jalopy's User Manual directly from the GUI interface.
2.2.7 The user will be able to import and export custom formatting conventions.

2.3 Formatting Rules

2.3.1 Indentation: Lets you change the general indentation settings.

2.3.1.1 Policy: Lets you choose the way lines should be indented.

1) Standard indent: With standard indentation, lines will be indented according to the current indentation level (Note that the indentation level changes as the block or parentheses level changes).
2) Deep indent: Deep indentation means that lines will be indented relative to the current parentheses or assignment offset. This way consecutive code sections are somewhat easier to recognize at the downside of consuming more horizontal space.

2.3.1.2 Sizes: Lets you set different indentation sizes.

1) General indent: Specifies the number of spaces to use for general indentation (Studies have found that 2 to 4 spaces for indentation is optimal)
2) Leading indent: Specifies the number of spaces to prepend before every line printed.
3) Continuation indent: Specifies the number of spaces that should be inserted in front of continuation lines, i.e. the consecutive lines in case of a line wrap.
4) Trailing comment indent: Specifies the number of spaces to insert between trailing comments and the preceding statement.
5) Extends indent: If enabled, specifies the whitespace to print before the extends keyword in case it was printed on a new line.[[br] 6) Implements indent: Specifies the whitespace to print before the implements keyword in case it was printed on a new line.
7) Throws indent: Specifies the whitespace to print before the throws keyword in case it was printed on a new line.

2.3.1.3 Align

1) Variable identifiers: If enabled, aligns the identifiers of variable declarations.
2) Variable assignments: If enabled, aligns the assignment parts of variable declarations or, surprise, assignments.
3) Method Call chains: If disabled, indentation happens according to the current indentation level.

2.3.2 Braces

2.3.2.1 Styles

1) C style. Sometimes called "Allman style" or "BSD style".

example

if (!isDone)
{
    doSomething();
}
else
{
    System.err.println("Finished");
}

2) Sun style. Sometimes called "K&R style".

example

if (!isDone) {
    doSomething();
} else {
    System.err.println("Finished");
}

3) GNU style.

example

if (!isDone)
  {
    doSomething();
  }
else
  {
    System.err.println("Finished");
  }

2.3.2.2 Wrapping: Controls the brace wrapping options.

1) Newline before left brace. If enabled, always prints a newline before the left curly brace.
2) Newline after right brace. If enabled, prints a newline after the left curly brace (when possible).

2.3.2.3 Whitespace: Controls the indentation whitespace for the left and right curly brace.

1) Before left brace. Number of spaces to print before the left curly brace.
2) After left brace. Number of spaces to print after the left curly brace.
3) After right brace. Number of spaces to print after the right curly brace.

2.3.2.4 Insert braces: Per definition braces are superfluous on single statements, but it is a common recommendation that braces should be always used in such cases. With this option, you can specify whether missing braces for single statements should be inserted for the control statements if, for, while and do-while.

example

while (!isDone)
    doSomething();

into

while (!isDone)
{
    doSomething();
}

2.3.2.5 Remove braces: It is permittable to remove braces in case they are superfluous. This not only applies to the control statements if, for, while and do-while, but also to every block in general (remember a block is just a sequence of statements, local class declarations and local variable declaration statements within braces).

example

for (int i = 0; i < 100; i++)
{
    sum += value[i];
}

into

for (int i = 0; i < 100; i++)
    sum += value[i];

2.3.3 Whitespace

2.3.3.1 Space before: Lets you choose the components that should get one leading space inserted before them.

1) Method declaration parentheses.
2) Method call parentheses.
3) Statement parentheses.
4) Braces.
5) Brackets
6) Case colon

2.3.3.2 Space after: Lets you choose what components should have one trailing space inserted after the component.

1) Comma
2) Semicolon
3) Type Cast
4) Negation

2.3.3.3 Spaces around: Controls what components should have both a leading and trailing space inserted. This is sometimes called "padding".

1) Assignment Operators
2) Logical Operators
3) Relational Operators
4) Bitwise Operators
5) Mathematical Operators
6) Shift Operators
7) Braces
8) Brackets
9) Parentheses

2.3.4 Wrapping: Controls when and how lines gets wrapped.

2.3.4.1 General: Lets you control the general line wrapping options.

1) Wrap lines: Enables or disables the automatic line wrapping.
2) Line length: Lets you specify the maximum line length. Jalopy tries (more or less) to limit each line within the given length.[[br] 3) Deep indent: Specifies the length after which a gap will be identified as "deep indented". Jalopy tries to avoid these kind of gaps and will force a line break or apply another indentation scheme, if this size is exceeded.

2.3.4.2 Policy: Lets you fine-control the wrapping behavior.

1) Wrap after left parenthesis: Lets you control the wrapping behaviour for statement and expression lists. If left disabled, the first line break will be preferably inserted behind the first parameter or expression and only occurs after the left parenthesis if the maximum line length would be exceeded.
2) Wrap before right parenthesis: Forces a line break before the right parenthesis of parameter or expression lists. The parenthesis will be intended according to the current indentation level. Only takes action if at least one parameter/expression was indeed wrapped. This switch affects the output style of method/constructor declarations and calls, creator statements and if-else, for, while and do-while blocks.
3) Wrap grouping parentheses: Lets you control the wrapping behavior for grouping parentheses. If enabled, linebreaks are inserted after left and before right parentheses of grouped expressions to let the expression(s) stand out.
4) Wrap after assignments: Lets you control the way wrapping takes action for assignments. If left disabled, line wrapping preferably occurs as part of the expression printing. Otherwise wrapping will be performed right after the assignment.
5) Wrap before operators: If enabled, lines will be wrapped before the operator. The operator will be printed with the continuation line.
6) Wrap after operators: If enabled, lines will be wrapped after the operator.

2.3.5 Blank Lines: Lets you specify the general blank lines sizes for different Java source file elements

1) Package statement: Lets you control how many blank lines should be printed after the package statement.
2) Last import statement: Lets you control how many blank lines should be printed after the last import statement.
3) Classes: Lets you control how many blank lines should be printed between two class declarations.
4) Interfaces: Lets you control how many blank lines should be printed between two interface declarations.
5) Methods: Lets you control how many blank lines should be printed between two method/constructor declarations.
6) Blocks: Lets you control how many blank lines should be printed before and after statement blocks (if-else , for, while, do-while, switch, try-catch-finally, synchronized). Note that the 'Blank lines after' setting also applies for anonymous inner classes.
7) Declarations: Lets you control how many blank lines should be printed before and after variable declarations.
8) Case blocks: Lets you control how many blank lines should be printed before each case block of a switch expression.
9) Control statements: Lets you control how many blank lines should be printed before the statements return, break and continue.
10) Single-line comments: Lets you control how many blank lines should be printed before single-line comments.
11) Multi-line comments: Lets you control how many blank lines should be printed before multi-line comments.
12) Javadoc comments: Lets you control how many blank lines should be printed before Javadoc comments.

2.3.6 Other*

1) Formatter will be able to place the default case after all the cases in a switch statement.
2) Formatter will be able to eliminate exact duplicate imports.
3) Formatter will be able to add trailing comma to array initialization.
4) Formatter will be able to check for @author and @version tags in each file.
5) Formatter will be able to modify array type definitions. ex. convert int x[] to int[] x.
6) Formatter will be able to add a header or a footer to a source code file.

* Features that may not be implemented.

3 Quality Attributes (Nonfunctional Requirements)

Operating Constraints

3.1 The extension will run on Java 1.4.2 or higher.
3.2 The extension will run on BlueJ version 2.0 or newer.

Platform Constraints

3.3 The extension will run on a processor of 600MHz or faster and a minimum of 64 megabytes of RAM.
3.4 The extension will run in any environment that BlueJ does.

Performance

3.5 The extension must format code at a rate equal to or faster than 1 second per 200 lines of code.

Reliability

3.6 The extension must never fail in such a way as to affect the stability of BlueJ.
3.7 The extension must correctly format selected source code files to the conventions specified by the user.

Deployment

3.8 The extension must be deployed as a jar file that conforms to all of the requirements for a BlueJ extension.

Usability

3.9 The configuration files must be editable in a standard text editor.
3.10 The preview panel in the Jalopy formatting preferences window must correctly display a preview that shows the effects that the selected formatting options have on the source code.
3.11 A user familiar with BlueJ who has installed BlueJalopy should not have to spend more than two minutes to format their source code in BlueJalopy.

4 Behavioral Requirements

Basic User Interface

See BlueJalopy's User's Manual.

Other

4.1 The formatting of a class must not make the class appear uncompiled in BlueJ.
4.2 A link to the Jalopy manual must be provided from the configuration panel.
4.3 When formatting an uncompiled source code file, the extension must attempt to compile it.
4.4 The "Undo" function must perform correctly from the Editor window.

5 Informational Requirements

5.0 Data Model

Figure 5.1 below shows the data model of the Java source code formatter extension for BlueJ, which is represented as a data flow diagram (DFD).



Figure 5.1 Data flow diagram of the source code formatter.

5.1 Data Dictionary

Data Dictionary

6 Appendices

6.1 External Interfaces

6.1.1 Software Interfaces

The BlueJ formatter extension will interface with the Jalopy code formatter to parse and format the code. Jalopy uses ANTLR to parse the java code. The BlueJ formatter extension is a wrapper around Jalopy to extend it's capabilities to the BlueJ IDE.

6.1.2 I/O Formats

The source code input files will be a text file with a .java extension to it. The formatted source code file will be text files with .java extension. The configuration file will be an xml file.

6.2 Engineering Analysis

Platform Choice (OS/Language)

Windows/Mac OSX/Linux are the currently supported OS platforms for the BlueJ IDE. These platforms will be supported by our extension. Since Java is portable there should be little concern about integrating the extension to all platforms. Java was chosen to develop the extension because the BlueJ IDE can be extended using the Java language.

User Interface

Because the formatter is designed for a student unfamiliar with programming the UI needs to be easy to use. In this way there several easy ways to run the formatter as discussed above. However, due to time constrains our team opted to use a configuration file to set the formatting rules before creating a GUI. This solution allows for customization while allowing the project to stay on time.

6.3 Negative Requirements

6.3.1 Formatter will not format uncompilable source code.

6.4 FTR Review Summery report - will take place at a later date.
6.5 This document has been reviewed for quality and adheres to the QA checklist found here.

7 Credits

See the Credits Page