Skip to content

Developers guidelines

Jump to bottom Edit New page
Kyriakos Chatzidimitriou edited this page Jul 2, 2013 · 3 revisions

Guidelines for the CASSANDRA platform developers.

#Technologies

List of technologies used in the development of the CASSANDRA platform:

  • Java
  • Ant
  • Git and github.com
  • Unit Testing
  • Continuous Integration
  • Logging
  • Design Patterns
  • Issues in github

##Java Programming in Java should follow strictly the Java code conventions document, while for writing javadoc comments one can use this How To guide.

Some of the basic guidelines taken from the Java code conventions documents for ease of use:

  • No files longer than 2000 lines
  • Each Java source has a single public class or interface. This class should be the first class in the file.
  • Ordering of sections in the file:
    1. Beginning comments (license information will be placed here via a script file, when making a release, so all the CASSANDRA Java source files will not incorporate any beginning comments)
    2. Package and import statements
    3. Class and interface declarations a. Class/Interface (C/I) javadoc b. C/I statements c. C/I comments not appropriate for javadoc d. public, protected, private variables e. Constructors f. Methods grouped by functionality rather than scope or accessibility. Makes reading the class easier.
  • Indentation 4 spaces, tabs every 8 spaces
  • Avoid lines longer than 80 chars, documentation no more than 70 chars.
  • Wrapping:
    • break after comma
    • break before operator
    • prefer higher level breaks than lower level
    • align the new line with the beginning of the expression at the same level on the previous line
    • if the above leads to confusing code, indent 8 spaces
      • if indentation should follow this rule
  • Implementation comments /…/ or // read by developers who have the source code
    • Block
    • Single line
    • Trailing
    • End-Of-Line
  • Documentation comments /**…*/ read by API users usually
  • No asterisk boxes and ascii art
  • No special chars
  • Declarations
    • one per line
    • put declarations at the beginning of the block
  • Class/Interface declarations
    • No space between a method and the parenthesis, for example "get("
    • Open brace “{“ appears at the end of the same line as the declaration statement
    • Closing brace “}” starts a line by itself indented to match its corresponding opening statement, except if “{ }”
  • Statements:
    • each line at most one statement
    • if statements always with braces
    • every switch statement should have a default case with a break statement
  • Blank lines
    • 2 blank lines
      • Between sections of a source file
      • Between class and interface definitions
    • 1 blank line
      • Between methods
      • Between local variables in a method and its first statement
      • Before a block or a single line comment
      • Between logical sections inside a method
  • Blank spaces
    • A keyword followed by a parenthesis
    • After commas
    • All binary operators except .
    • for
    • casts should be followed by blank
  • Naming
    • Classes: nouns in mixed case with initial capital, simple and descriptive, No abbreviations
    • Interfaces: Same as class names
    • Methods: verbs mixed case with initial small
    • Variables: mixed case with a lower-case first letter
    • throwaway: i, j, k, m, n for integers and c, d, e for chars
    • Constants: Uppercase separated by _
  • Unless good reason don’t make it public
  • Don’t use objects to call static methods
  • Use parenthesis in involved operations
  • Special comments:
    • XXX: bogus but works
    • FIXME: bogus and broken
    • TODO: for todos

We also have some guidelines of our own:

  • In front of arguments in methods, put prefix "'a' (for argument)" to avoid the use of this and clutter code. For example:

public void setName(String aName) { name = aName; }

##Ant

Ant will be used in order to build the project.

The project file tree is defined as (alphabetical order):

  • '''root'''
    • '''bin''' (compiled binaries)
    • '''dist''' (the folder should contain the final distribution file tree ready to run the platform)
    • '''doc''' (documentation folder)
      • '''api''' (javadoc documentation)
    • '''jar''' (any jar files produced)
    • '''lib''' (required libraries)
    • '''models''' (CASSANDRA entity models)
    • '''resources''' (any resource files needed)
    • '''scripts''' (any necessary scripts for development, execution and version control)
    • '''src''' (any source files)
      • '''java''' (java source files)
    • '''tests''' (all unit tests)

The following targets (should) exist:

  • build : builds the project
  • clean : cleans any produced files and directories
  • run : run the project, must check if a build is required
  • test : perform testing
  • dist : bundle everything required for the CASSANDRA platform to run standalone into the '''dist''' directory for distribution purposes

##Git

The version control system of choice is Git and the repository is hosted on github.com. We will rely heavily on the development procedure paradigm of http://nvie.com/posts/a-successful-git-branching-model/ .

Branches

  • Master (Remote)
  • Developer (Remote)
  • Features-XXX (Local)
  • Releases (Local)
  • Tags (Remote)
  • Hotfixes (Local)

In boldface characters the branches mostly used by developers. The other branches will be mainly used by the integrator.

Initialization

  1. Become a member of the https://github.com/cassandra-project by contacting Kyriakos Chatzidimitriou: kyrcha [at] iti (dot) gr or kyrcha [at] gmail (dot) com
  2. Go to your workspace directory
  3. git clone [email protected]:cassandra-project/platform.git. This will create all the directory structure from the present working directory and up
  4. cd platform
  5. git checkout develop Switch to the develop branch that is set-up to track remote branch develop
  6. git checkout –b feature1 develop Create a new local branch from develop for you to work on

The daily grind

  1. While in the develop branch do a git pull origin develop, in order to get the changes in the remote repo by others
  2. git checkout –b feature1 develop Create a new local branch from develop for you to work on
  3. Develop and test your feature1
  4. git add and git commit your feature1 changes to files
  5. git checkout develop switch to develop branch
  6. git merge –no-ff feature1 merge the changes by maintaining the branch of change with no fast forward
  7. git branch –d feature1 delete merged branch
  8. git push origin develop push to remote repository

Release and tag branches

NB: to be used by the integrator

  • Release branch and tags:
  • git checkout -b release-1.2 develop
  • ./bump-version.sh 1.2
  • git commit -a -m "Bumped version number to 1.2“
  • git checkout master
  • git merge --no-ff release-1.2
  • git tag -a 1.2
  • git checkout develop
  • git merge --no-ff release-1.2
  • git branch -d release-1.2
  • git push origin 1.2 or git push origin --tags

Hotfix branches

NB: only if fixes need to be made at old releases

  • git checkout -b hotfix-1.2.1 master
  • ./bump-version.sh 1.2.1
  • git commit -a -m "Bumped version number to 1.2.1"
  • git commit -m "Fixed severe production problem“
  • git checkout master
  • git merge --no-ff hotfix-1.2.1
  • git tag -a 1.2.1
  • git checkout develop
  • git merge --no-ff hotfix-1.2.1
  • git branch -d hotfix-1.2.1

Useful commands

Resources

Connecting changes to issues

Include, for example, in the message when making a git commit -m "message" Issue #3 in order for this specific commit to be associated with Issue #3.

Comment Template

TBD

Hooks

TBD

Continuous Integration

TBD but we will use one of the solutions below:

  • Jenkins
  • CI-Joe
  • cron jobs

##Unit Testing

TBD but we will use one of the solutions below:

  • Mockito
  • jUnit

##Eclipse If you are using eclipse useful plugins to consider are:

Also in order to be in accordance with the Java Code Conventions document perform the following set-up:

Window > Preferences > General > Editors > Text Editors

and set-up:

  • Display tab width: 4
  • Check insert spaces for tabs
  • Show print margin
  • Print margin column: 80

Egit is not a very good idea based on our development process and shell (Mac/Unix) or git-bash (Windows) is the recommended way to go for connecting with github. The reason is the Egit does not support the --no-ff option.

Design Patterns

Where appropriate we will use software design patterns.

Issues in github

When you discover a bug in the platform, put it as an issue with a simple but informative title and in the description write:

  • How to reproduce the bug in details and how often it appears
  • What should have happened at least in your opinion
  • What actually happened
Add a custom footer
Add a custom sidebar
Clone this wiki locally