Luna SRS

1.0 Introduction

1.1 Scope

ChangeStyle is a style formatter extension for the BlueJ Java IDE (Integrated Development Environment). Many college classrooms or software companies require programmers to conform to a very rigid and often arbitrary coding style. Oftentimes a programmer has difficulty conforming to these new style rules at the expense of development time. ChangeStyle provides an unobtrusive way for any programmer working with BlueJ to convert their code to any common coding style in seconds. ChangeStyle makes jobs that require a strict coding style guidelines less tedious and gives programmers more leeway in their coding (thus increasing efficiency). This extension |reduces the time spent manually reformatting code, so that time can be used for more productive and less tedious tasks.

1.2 Product Features

ChangeStyle goes beyond just checking coding style. It automatically formats code depending on the options the user specifies. The user can modify a configuration file to suit their Style Preference. ChangeStyle formats the specified file(s) on demand by using the Style Preference configuration file given. Some key features include formatting only a selected section of code and setting the format settings to preset Style Preferences such as K&R Style and Sun Style. Some of the important formatting rules are listed below:

1. Insert and Remove Indentation

2. Enforce Brace Style

3. Line Wrapping

4. Javadoc Formatting and Creation

A full list of the ChangeStyle's features can be found in the Functional Requirements section (section 2.0).

1.3 User characteristics

ChangeStyle is designed for Computer Science college students, from Freshman to Senior standing. The students must be competent with the English language. These students may have introductory knowledge of programming and be unfamiliar working with IDE's however it is assumed that they are at least somewhat familiar with BlueJ.

1.4 Constraints

ChangeStyle uses Jalopy as the core Style Formatter and provides a UI (User Interface), more functionality, and extends BlueJ. The project time frame is limited to less than 22 non-consecutive weeks. All the developers have other ongoing obligations throughout the development life-cycle of ChangeStyle. The limited time may influence the outcome of the software product.

1.5 Assumptions and Dependencies

The developers assume the following dependencies during the construction of ChangeStyle:

1. A BlueJ Extension API is readily available for reading

2. The development team has access to the BlueJ IDE Program

3. Jalopy has an API that is readily available for reading

4. Jalopy’s code is open source and noncommercial for use

2.0 Functional Requirements

2.1 Program Requirements

The dots ("▪") represent the relative importance of a specific requirement as stated by the Client. The more dots, the more important.

2.1.1. ▪▪▪ : Formats source code in the BlueJ editor window on demand (does not format on the fly).

2.1.2. ▪▪▪ : The user can edit the Style Preferences through the Style Preference GUI interface.

2.1.3. ▪▪▪ : The user may specify or use default Style Preferences

2.1.4. ▪▪▪ : Presents the user the option to choose from preset Style Preferences (such as the GNU or JAVA styles) as well as user's Style Preferences.

2.1.5. ▪▪▪ : Immediately after ChangeStyle formats the code, the user may restore the file to its state right before the format occurred.

2.1.6. ▪▪▪ : Support all standard BlueJ class types {Class, Abstract Class, Interface, Applet, Unit Test, Enum}.

2.1.7. ▪▪▪ : Available External Documentation (user manual).

2.1.10. ▪▪ : Has the ability to format multiple files at the same time (i.e. all source code in a package.) Also have the ability to format just one file at a time.

2.1.12. ▪ : ChangeStyle will only format compliable code.

2.1.13. ▪ : ChangeStyle only formats files ending in '.java'.

2.1.14 : Every panel in the settings dialog will have a personal help link linking to the corresponding section in the Jalopy User Manual, if the section is available.

2.1.15 : Customized Conventions ChangeStyle will allow the user to modify predefined conventions and save them as customized conventions that will appear in the conventions drop down box along with the original predefined conventions.

2.1.16 : Batch Undo ChangeStyle implement Batch Undo, which presents the user with a dialog with a selectable list of files which can be undone, while displaying files which cannot be undone in grey.

2.1.17 : Editor Update Changes made by ChangeStyle’s formatting are visible immediately in the editor window, and when the Undo button is selected in the editor window, the editor window shows the undone code.

2.1.18 : Import/Export The import and export convention functionality for ChangeStyle is located in the Preferences Panel and is designed based on the approved UI prototype.

2.1.19 : Headers/Footers ChangeStyle allows the user to replace Headers and Footers containing some user-specified text in the corresponding panels and offers a help link to a new section in the User Manual describing Headers and Footers in more detail.

2.1.20 : Status Panel Every time a class or project is formatted by ChangeStyle, the 'status panel' at the bottom of BlueJ's window displays "Formatting... Done." When the undo feature is selected, the window will display "Undo Formatting... Done"

2.1.21 : Preference Panel When the users clicks, the "Edit..." button, no matter how many times, the Preferences panel only appears once.

2.2 Style Rules

The dots ("▪") represent the relative importance of a specific requirement as specified by the Developers. The more dots, the more important. Each of these rules can be turned on/off (i.e.: in use or not). Each rule can also be configured.

2.2.1. ▪▪▪▪ : Changes the placement of left curly braces. (beginning of line or new line).

2.2.2. ▪▪▪▪ : Changes the placement of right curly braces. (beginning of line or new line).

2.2.3. ▪▪▪▪ : Indents each block (i.e. ChangeStyle indents the each nested block one tab more than the previous block) {or keeps everything on the same line}. Can change the amount of indentation (i.e.: tab size).

2.2.4. ▪▪▪ : Wraps lines longer than a specified number of characters.

2.2.5. ▪▪▪ : Places each variable declaration in its own statement and on its own line or groups them together.

2.2.6. ▪▪▪ : Adds padding to parentheses; that is whether there is space after a left parenthesis and before a right parenthesis, or if such spaces are forbidden.

2.2.7. ▪▪▪ : Changes tab characters ('\t') into spaces {and vice versa}.

2.2.8. ▪▪▪ : Surrounds a token with whitespace if necessary {or remove it }.

2.2.9. ▪▪▪ : Creates a newline at the end of each file {or remove them }.

2.2.10. ▪▪▪ : Eliminates redundant (exact duplicate) imports.

2.2.11. ▪▪▪ : Has specific Try-Check Formatting. {or not }, has specific style for Try-Check functions.

2.2.12. ▪▪▪ : Sorts the parts of a class or interface declaration (Class variables followed by Instance variables, Constructors and Methods in that order) {or not}

2.2.13. ▪▪▪ : Adds/removes whitespace '\n' characters between methods.

2.2.14. ▪▪▪ : Adds/removes whitespace '\n' characters between a method and its preceding (javadoc) comment.

2.2.15. ▪▪▪ : Adds whitespace before or after assignment ("="). NOTE: this can be asymmetric (i.e. "x= 3").

2.2.16. ▪▪ : Adds trailing comma to array initialization {or remove them}.

2.2.17. ▪▪ : Inserts (if necessary) braces around code blocks. Inserts braces around if/else branches and loop-bodies, even when they are only a single statement.

2.2.18. ▪▪ : Places 'default' case after all the cases in a switch statement.

2.2.19. ▪▪ : Inserts padding of spaces before or after parentheses for typecasts and structs {or removes them}.

2.2.20. ▪▪ : Creates padding (if necessary) between the identifier of a method definition, constructor definition, method call, or constructor invocation and the left parenthesis of the parameter list.

2.2.21. ▪▪: Modifies javadoc headings to follow javadoc template. Can insert javadoc headings with preset @author or @version tags.

2.2.22. ▪▪ : Verifies that '@param' tags agree with the parameter's actual name. If they disagree, change the @param to match the code.

2.2.23. ▪ : Modifies the style of array type definitions. Only supports converting to the “int[] x” form.

2.2.24. ▪ : Turns inline conditionals into if() statements.

3.0 Quality Attributes (Nonfunctional Requirements)

Performance requirements (see appendix)

3.0.1. Minimum: 64MB main memory, Pentium II processor or equivalent Recommended: 128MB main memory, 400MHz Pentium III processor or above

3.0.2. ChangeStyle does not take more than 10 seconds to format 1000 lines of code.

Operating constraints

3.0.3. J2SE 1.6.0 (Java 2 SDK version 1.6.0) or newer must be installed.

3.0.4. ChangeStyle runs on BlueJ 2.2 or newer

Platform constraints

3.0.5. ChangeStyle runs on Windows XP (SP2) and Mac OSX and Linux

Accuracy and Precision

3.0.6. ChangeStyle formats compiled code according to Jalopy’s formatting convention standards.

Modifiability

3.0.9. The user can add and modify Style Preferences through the UI Portability

3.0.10. ChangeStyle is an extension to BlueJ which only runs on the Java Runtime Environment Reliability

3.0.11. ChangeStyle’s Mean Time Between Defects (MTBD) is greater than 30 formats.

3.0.12. ChangeStyle does not format on uncompilable .java files.

Security

3.0.14. ChangeStyle does not add any new expressions to the formatted code.

Usability

3.0.16. A Computer Science student can download and install ChangeStyle in less than 30 minutes on a computer that has BlueJ already installed.

3.0.17. A Computer Science student can format a .java file in BlueJ that has ChangeStyle already installed in less than 5 minutes.

3.0.18. Formatting a file using the currently set Style Convention takes less than 4 clicks.

Legal

3.0.19. ChangeStyle has a BSD License and any program that uses (or extends) ChangeStyle must also have a BSD License.

3.0.20. License:

Copyright (c) 2008, LUNA SOFTWARE (Tracy Davies, Mark Carpenter, Richard McDaniel?, Ian Stewart, Paul De Leon, and Stephanie Long) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name of LUNA SOFTWARE nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

3.0.21. ChangeStyle does not incorporate any program which requires the user to buy a license.

3.0.22.Use at your own risk!

4.0 Behavioral Requirements

4.0.1. Easy install - one-file download as installation (assuming the requisite versions of the Operating System, Java and BlueJ are installed).

4.0.2. The ability to format all files in a project at once.

4.0.3. The ability to format one .java file.

4.0.4. ChangeStyle's Editor can edit the Style Preference Configuration Files .

5.0 Informational Requirements

5.1 Data Model Illustrates the various functionalities of ChangeStyle and how the different files interact with each other for each.

fig 5.1.1

More, specific, information below.

Format Code

fig 5.1.2

BlueJ provides the Source Code which, combined with a Style Preference Configuration File and run through ChangeStyle "Formatter", creates the Formatted Code which can be viewed by the USER. ChangeStyle also creates a Backup Code file which is used if the user wants to 'undo' the formatting. Which Style Preference Configuration File to use is determined by information contained in the Settings File.

Edit Style Preferences

The USER uses ChangeStyle "Editor" to view and modify a Style Preference Configuration File.

The USER uses any XML editor to view and modify a Style Preference Configuration File directly.

Edit Style Preferences

The USER uses ChangeStyle "Editor" to edit the Settings File

5.2 Data Dictionary

The dots ("▪") represent the item is a composite. See java.sun.com/docs/glossary.html for additional terms.

---

name	Backup Code
alias	Backup (Unformatted) Source Code
description	A copy of the unformatted code to be held on to in case the user decides to 'undo' the formatting.
supplementary	Stored wherever the user wants it to be. If not specified then defaults to "/bluej/extensions/changestyle/"

---

name	▪ChangeStyle
alias
description	A Style Formatting extension (plug-in) for BlueJ.
supplementary	Has two main functionalities ChangeStyle "Edit" and ChangeStyle "Format".

---

name ▪ChangeStyle "Editor"
alias	Style Preferences Configuration File Editor
	Settings File Editor
description	Lets the user modify the Style Preferences Configuration File(s) or the Settings File.
supplementary	As an alternative to editing the file directly, the user can interact through the GUI (Editor).

---

name	▪ChangeStyle "Formatter"
alias	Source Code Formatter
description	Takes the Source Code and replaces it with Formatted Code. Uses the Settings File, a specified Style Preference Configuration File and the Jalopy Core. Also saves a Backup File which can be used to restore the Source Code.

---

name	Formatted Code
alias	Formatted Source Code
description	Every time ChangeStyle "Formatter" runs successfully it replaces the Source Code with the Formatted Code which is a result of the Source Code and a specific Style Preference Configuration File being fed through the Jalopy Core.
supplementary	Stored the same place the Source Code was (replaces the source code).

---

name	▪Jalopy
alias	Jalopy Core
description	A Style Formatter with no user interface or BlueJ extensibility. ChangeStyle "Formatter" acts as a shell around Jalopy.
supplementary	An open source software. http://jalopy.sourceforge.net/

---

name	▪Project Folder
alias	BlueJ Project Folder
	BlueJ Project
	Project
description	BlueJ groups together files into Projects.
supplementary	The functionality of ChangeStyle is geared to work within the framework of these Projects. The entirety of Project Folder can be Formatted at once.

---

name	Settings File
alias	BlueJ's Settings File
description	BlueJ's Settings File which stores ChangeStyle's settings.
supplementary	stored as BlueJ.ini

---

name	Source Code
alias	Unformatted Source Code
description	The original file where all the changes take place. This file is taken by ChangeStyle "Formatter" and is replaced by the Formatted Code.
supplementary	Stored wherever the BlueJ project is.

---

name Style Preference
alias	Style
	Coding Style
	Format (noun. not to be confused with the verb)
description	A collection of Style Rules that cohesively make up a particular 'style' of coding.
supplementary	Examples: K&R Style, Sun Style, C Style

---

name	Style Preference Configuration File
alias	Style Preference Config. File
	Style Preference File
description	The actual file that holds one entire Style Preference. Can be edited either by ChangeStyle "Editor" or by the user manually.
supplementary	There can be many different Style Preference Configuration Files but ChangeStyle uses just one to Format the Code. The Style Preference Configuration File is an XML file.

---

name	Style Rule
alias	formatting rule
description	A specific way of writing a portion of code. Each way does not change the functionality of the code itself, but can make the code clearer and easier to understand (especially to those who are familiar with the Style Rule)
supplementary	The classic example is whether to have braces around an if( ) statement on the same line or the line following the if( ) statement as shown below:

if ( ) {

/* ... */

} or if ( ) {

/* ... */

} or if ( )

{ /* ... */ }

each of these ways of writing if( ) statements is perfectly legal and is its own Style Rule.

---

name	▪User Interface
alias	UI
description	the graphical, textual, and even auditory information the program presents to the user.
supplementary	CheckStyle? will be using a GUI (Graphical User Interface) which means that it will interact with the User using windows and other "point-and-click" means.

---

name	XML
alias	.xml
	eXtensible Markup Language
description	A standard for creating markup languages which describe the structure of data. It is not a fixed set of elements like HTML. Is a metalanguage: a language for describing other languages.
supplementary	XML files can be read and edited by a large number of free or even open-source editors.

6.0 Appendices

6.1 External Interfaces

6.1.1 Hardware interfaces

A desktop computer and laptop computer with an external mouse or touchpad mouse and a keyboard. 6.1.2 Software interfaces

The extension uses BlueJ version 2.2 or higher as well as the installed version of the java runtime environment, options being JDK 5, JDK 6, or J2SE 1.4.2. ChangeStyle uses the Jalopy Core to actually Format the files. The Style Preferences are stored in XML files.

6.1.3 Communications interfaces

None.

6.1.4 I/O formats

The extension formats input in the form of java source code, that is .java files, and outputs formatted Java files. The input devices are a mouse and keyboard and communication is done via a GUI. ChangeFile? accesses and modifies the Settings File as well. The Style Preference Configuration File is stored as a XML file. The Backup File is stored in BlueJ's Project Folder or another place as specified by the user. (another likely location: /bluej/extensions/changestyle/)

6.2 Issues and Tradeoffs - Engineering Analysis of Requirements

6.2.1.: Which input devices can the user need to uses the formatter?

Alternative 1: Keyboard and mouse.

Pros:

With the keyboard, the user can input keyboard shortcuts to menu; ex. Ctrl-shift-F With the mouse, the user can click buttons and select formatting options. Is faster and less tedious to use shortcut keys such as [tab] and [enter] and the a arrow keys

Alternative 2: Mouse only.

Pros:

This allows for users without a keyboard to format files.

Cons:

This requires implementation of an interface for inputting characters (virtual on-screen keypad)

Alternative 3: Keyboard only.

Pros:

This allows for users without a mouse to format code.

Cons:

This requires the user to press series of keys for simple operations that will only take a single moment to execute with a mouse.

Decision: Keyboard and mouse

Justification: Can easily select options for formatting and increased versatility

6.2.2.: Does ChangeStyle run on compliable code only?

Pros:

Offers more predictable results.

Cons:

Offers unpredictable results. The formatted code may result differently than what the User intends.

Decision: Only runs on compliable code.

Justification: ChangeStyle is a Style Formatter, not a debugger. The developers feel that it would be overstepping ChangeStyle's bounds to offer programming advice.

6.2.3.: How will the fundamental functionality be set up?

Alternative 1: One Function. When called, ChangeStyle asks for Style Preferences then proceeds to Format the Code.

Pros:

The user can change their Style Preferences every time they go to Format their code.

Cons:

The user will have to confirm their Style Preferences every time they go to Format their code.

Alternative 2: Dual Functionality. An Editor and a Formatter. The Editor allows the User to modify Style Preferences and the Formatter allows the user to Format the code.

Pros:

Gives the User more control and lets them either change the Style Preferences or Format the code. Streamlines the program and makes it cleaner.

Cons:

To save Code to a completely new Style will require a few more steps.

Decision: Dual Functionality

Justification: Keeps ChangeStyle unobtrusive minimizes overlap in what the User has to see. The User will (presumably) want to actually modify Style Preference Files very infrequently.

6.3.0 FTR Review See Attached.

6.4 QA Checklist See Attached.