Great code is the base for a great project.

We are trying to make Wise a great project and to make it possible we agreed about some guideline and tools to write better, easy to read and with an uniform style. We are using eclipse as IDE, and we are using some good stuffs it (and some plugins) drive to us to achieve our goals. Would you like to contribute, but you are using another IDE? Well enrich this page describing how to get same goals with IDE xyz would be a first contribution

-

Code Style

We have defined a code style profile for eclipse. You can find it on the subversion on the file named wise-code-formatter-profile.xml

Please use it setting your Project properties "Java CodeStyle/Formatter". Please set also on "Java Editor/Save Actions" the preference to format code (all lines) on save. Use the same style make code easier to read and don't generated false difference on SCM due to different formatting.

eclipse-preferences.epf

You will find in svn also an Eclipse preference file. Import it into your workspace (may I suggest you to use a dedicated workspace if you don't want to mix preference for different project area?). What is it supposed to do? It change some standard preference for workspace (you can take a look to it, it isn't hard to read). Some example: force to add JBoss.org licence on new created classes, make easier some static import useful for our tests, mark as error some situation normally marked as warning (remember great code?).

Javadoc

Well, what we think about is simple: if you provide a Javadoc provide it something useful and maintain it. For this reason our Eclipse preference mark as error Javadoc out of synch with the code. More General our policy about Javadoc is to always provide them on public interface, and limit this kind of documentation to its purpose: document the API usage. Don't put user manual in Javadoc, keep this kind of docs in dedicated documents, external of code

Concurrency annotation

We are using jcip annotation to mark concurrency contract of classes. They help a lot during interfaces/classes design forcing programmers to careful think about, and help a lot us to communicate clearly our intention about concurrency each other. Moreover they are exposed in JavaDoc enriching them of Thread safe information. And last but not least they are used by findbugs (see after on this page) to verify some concurrency correctness compile time.

Findbugs

Findbugs is "a program which uses static analysis to look for bugs in Java code". We are using its Eclipse plugin that show during normal works possible bugs in your code. In our experience it helps a lot to write better code, not only in terms of bugs, but also readability and efficiency. In the svn you will find .fbprefs file with our findbugs preference (all at maximum in fact)

Test: Unit test, the BDD approach

We are trying to get a full test coverage of our code with unit tests. We are using a BDD approach because it have several advantage. We consider this 2 links a must read to best understand what are these advantages:

• Testing behaviours

• BDD

Do you need some examples? Our test-src directory could be a good starting point.

Test: integration tests

We have some integration tests which take care of deploy a real WS on a real JBoss AS and then run test against it. When are you supposed to write integration tests? When you addition are well verified by unit tests, but needs some more verification to be sure the integration client/server is fine. IOW all main feature (mappings, WS- support and so on) should have an integration tests

Test coverage

We are using cobertura as coverage tool. It is included in our ant's build file under "coverage" target. Ideally when you contribute with some code you shouldn't get a lower coverage than before you contribution. IOW for each code added, please add tests to verufy it.

Continuos build

To be completed

Jira

We are using Jira to track issues and fix our roadmap. We always try to define next scheduled versions and the succeeding one, fixing for them release date. Any contributor who would take over a issue would ideally define or update evaluated complexity and mark issue resolved when he have implemented solution and provided a unit test for it. Please have a look to "Subversion commit messages" paragraph too. We try to use subtask to split issues in shorter and easier to track steps.

Subversion commit messages

We are using fisheye and subversion plugins in Jira. To make them work properly commit messages should contain the name of the issues resolved in that commit. For example "WISE-1". Any other descriptive text is welcome, but not strictly necessary. Ideally a commit would be referred to a single issue, even if sometimes it isn't possible or good (i.e. subtask)

For svn layout and our policy on branching and taggin plese refer to Wise/SubversionLayout