General programming standards and conventions

Key principles

communicate and work with team members (remote and local) often
write tests first before production code
check in code which is fully tested including unit tests and/or integration tests
check in code which is fully documented using javadocs
check in code which does not have any Eclipse warnings

Enable Subversion keyword expansion

Since we are using Subversion for our code repository, it would be nice to enable the keyword expansion so that our source files can be commented with auto-generated information such as last committed date, last committed author, etc. Subversion disables the keyword expansion by default. See A Crash Course in Subversion for more detailed information. Hence, we have to manually enable this feature. This means that keyword expansion must be enabled manually on a per-file basis. This can be changed to occur automatically from the client side via the configuration file for the Subversion client.

Here are the basic steps to enable Subversion keyword expansion for all your Subversion projects

Open your Subversion config file in an editor, usually located in <HOME_FOLDER>/.subversion/config.
- On Windows, it is usually C:\Documents and Settings\<username>\.subversion\config
- On Mac OS X, it is usually /Users/<username>/.subversion/config
- On linux or other unix variants, it is usually /home/<username>/.subversion/config

Uncomment the 'enable-auto-props = yes' option under the '[miscellany]' heading like so:

.subversion/config

...
[miscellany]
global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store target
enable-auto-props = yes
...

Add the following list of file types and their associated keywords and end-of-line style:

.subversion/config

...
[auto-props]
*.bat = svn:keywords=Id Author Date Url Revision;svn:svn:eol-style=native
*.bsh = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.c = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.cpp = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.css = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.dtd = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.groovy = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.h = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.html = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.java = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.jmx = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.js = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.jsp = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.jws = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.pl = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.pm = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.properties = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.py = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.rb = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.rdf = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.rss = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.sh = svn:keywords=Id Author Date Url Revision;svn:eol-style=native;svn:executable
*.sql = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.txt = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.vsl = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.wsdd = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.wsdl = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.xhtml = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.xml = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.xsd = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.xsl = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.xslt = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
Makefile = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
*.bmp = svn:mime-type=image/bmp
*.gif = svn:mime-type=image/gif
*.ico = svn:mime-type=image/x-icon
*.png = svn:mime-type=image/png
*.jpeg = svn:mime-type=image/jpeg
*.jpg = svn:mime-type=image/jpeg
*.pdf = svn:mime-type=application/pdf
*.tif = svn:mime-type=image/tiff
*.tiff = svn:mime-type=image/tiff
INSTALL = svn:keywords=Id Author Date Url Revision;svn:eol-style=native
README = svn:keywords=Id Author Date Url Revision;svn:eol-style=native

Java specific standards and conventions

follow Sun's guideline for code conventions
use SPACES only (4 spaces), no TABS for indentations
limit lines to no longer than 80 characters
to change the Java editor formatting in eclipse, look under Windows > Preferences menu, then select Java > Code Style > Formatter

Eclipse specific standards and conventions

you can configure project wide settings for different text editors with consistent formatting standards
use SPACES only (4 spaces), no TABS for indentations
limit lines to no longer than 80 characters
to change the CSS editor formatting, look under Windows > Preferences menu, then select Web and XML > CSS Files > CSS Source
to change the HTML editor formatting, look under Windows > Preferences menu, then select Web and XML > HTML Files > HTML Source
to change the JavaScript editor formatting, look under Windows > Preferences menu, then select Web and XML > JavaScript Files > JavaScript Source
to change the XML editor formatting, look under Windows > Preferences menu, then select Web and XML > XML Files > XML Source
to change the comments on top of every file, look under Windows > Preferences menu, then select Java > Code Style > Code Template

Test specific standards and conventions

test classes should be named to reflect the actual class being tested, i.e. MyClassTest.java for MyClass.java
test method names should reflect the actual method name being tested, i.e. testGetSavedData() for getSavedData()
if there are multiple tests for a single method, then use an underscore _ and then append the intention to the test name, i.e. testGetSavedData_NoValidDataShouldGenerateException() and testGetSavedData_DbFailure()
generate an AllTests.java junit test suite within Eclipse for each test package
1. within Eclipse, select the desired package in the explorer panel
2. select File -> New -> Other...
3. in the new wizard dialog box, select Java -> JUnit -> JUnit Test Suite
include each package's AllTests.java into the top level AllTests.java test suite
verify that the number of tests between running "mvn test" on the command line is the same as running the AllTests.java in the default package from within Eclipse. This is to make it possible to support running tests with both Maven 2 and Eclipse.

Table naming conventions

tables should be named as a pluralized form of the classname, using "_" to separate subwords (not camelcase), and they should all be lower-case. For example, the GrantedAuthority table should be named "granted_authorities"
join table names should have "related_to" between the table names that it joins. For example, a table that joins "users" table and "granted_authorities" table should be named "users_related_to_granted_authorities"

Unit tests

unit tests should be using JUnit 3.8.x as the test harness framework
unit tests should use mock objects provided by Easy Mock when other collaborator objects involve extensive set up, i.e. database, network resources, etc.
unit tests should not have any dependencies between each test method, i.e. a value stored into a variable from one test and read back and verified in another test
unit tests should run and pass from within Eclipse and from the command line as well:
```
mvn test
```

Integration tests

Integration tests (sometimes called system tests) are tests which combine different components within the system to validate the proper interactions at the functional level. Examples of integration tests include testing with an external database, testing with the application server, testing with the external SDS, and testing that involves the Spring container, etc. Integration tests are often more time consuming to write and may require custom built harnesses (test database, servlet container, etc.) to support these tests. However, they provide reassurance that the system (with its different components) does operate properly.

integration tests should use the Spring framework container to instantiate and wire all system level beans, all required dependencies that should be injected into a bean must be marked with the @Required annotation
integration tests should be written for all Data Access Objects(DAOs) since they are meant to interact with external data store mechanisms, both local database and SDS
integration tests should be written for other external components that are not part of the DAOs (nothing at this point but potential components may include search engines, etc.)
integration tests for services are not necessary as long as they use DAOs to interact with the data stores from within the service
integration tests that simply needs to have a Spring container should extend net.sf.sail.webapp.junit.AbstractSpringTests
integration tests involving the external SDS using HTTP REST should extend from net.sf.sail.webapp.junit.AbstractSpringHttpUnitTests as it provides SDS interaction methods
integration tests involving the database should extend from net.sf.sail.webapp.junit.AbstractTransactionalDbTests as it is configured to use an in-memory HSQLDB database just for the purpose of testing

Acceptance tests

Not done at this time.