perfsonar development work

Author: nordunet.behrmann
Date: 2012-12-21 09:51:00 +0000 (Fri, 21 Dec 2012)
New Revision: 6077

Added:
   trunk/README.txt
Modified:
   trunk/BUILDING.txt
Log:
Add README.txt

Issue: PSSERVICES-599

Modified: trunk/BUILDING.txt
===================================================================
--- trunk/BUILDING.txt  2012-12-21 09:14:49 UTC (rev 6076)
+++ trunk/BUILDING.txt  2012-12-21 09:51:00 UTC (rev 6077)
@@ -1,17 +1,3 @@
-PerfSONAR Java Services
-=======================
-
-PerfSONAR consists of several subproducts, such as the Measurement
-Archives (MA) SQL MA and RRD MA, the Measurement Points (MP) OWAMP MP
-and BWCTL MP, and the Lookup Service (LS). Some of these are written
-in Java, collectively called the PerfSONAR Java Services. These
-include the MAs and the LS. 
-
-Notably, the MPs are not written in Java and are hosted outside of
-this repository. The UI is written in Java, but still not considered
-part of the PerfSONAR Java Services and not hosted in this repository.
-
-
 Building PerfSONAR Java Services
 --------------------------------
 

Added: trunk/README.txt
===================================================================
--- trunk/README.txt                            (rev 0)
+++ trunk/README.txt    2012-12-21 09:51:00 UTC (rev 6077)
@@ -0,0 +1,135 @@
+PerfSONAR Java Services
+=======================
+
+PerfSONAR consists of several subproducts, such as the Measurement
+Archives (MA) SQL MA and RRD MA, the Measurement Points (MP) OWAMP MP
+and BWCTL MP, and the Lookup Service (LS). Some of these are written
+in Java, collectively called the PerfSONAR Java Services. These
+include the MAs and the LS. 
+
+Notably, the MPs are not written in Java and are hosted outside of
+this repository. The UI is written in Java, but still not considered
+part of the PerfSONAR Java Services and not hosted in this repository.
+
+
+
+Coding style
+------------
+
+Syntactic conventions are described and enforced using
+checkstyle. Please consult the checkstyle configuration, e.g., in
+perfsona_base/src/checkstyle/checkstyle.xml.
+
+Due to plenty of legacy code, some modules use a slightly relaxe set
+of rules. This is only to accomodate legacy code and any checkstyle
+warning should be considered a violation in new code.
+
+
+
+Programming methodology
+-----------------------
+
+PerfSONAR does not follow a formally defined programming methodology.
+
+Some rules do apply, though:
+
+- Code in subversion MUST compile; if a commit breaks compilation it
+  MUST either be fixed immediately or the change MUST be reverted.
+
+- Code in subversion should be releasable at any time, i.e., code you
+  know is incomplete or broken MUST not be committed.
+
+  This is not to say that we expect trunk to be perfect always, but
+  you should not commit code that is known to introduce regressions.
+
+- Code in subversion should have been tested, i.e., before committing
+  a change you MUST have tested said code.
+
+  Ideally code is tested using unit tests, but informal tests are 
+  acceptable too.
+
+- Code in subversion MUST pass unit tests.
+
+  If a commit breaks unit tests then the code MUST be fixed right 
+  away or MUST be reverted.
+
+- Unit tests MUST not be integration tests.
+
+  I.e. don't write unit tests relying on external services (or any
+  external resources, for that matter).
+
+  If you need integration tests use one of the Maven integration
+  test plugins and bind it to the Maven validation phase.
+
+- Commits MUST have a descriptive commit message.
+
+  Begin each commit with a short one-line (max 65 characters)
+  description. If applicable, begin this description with a module
+  name followed by a colon.
+
+  Add one or two empty lines after the description, followed by a
+  detailed description of the change. Typically the status quo SHOULD
+  be described, together with an argument why the status quo must be
+  changed, followed by a description how the change solves the
+  problem.
+
+  If applicable, add references to JIRA issues or other external
+  information that may help in understanding the commit.
+
+- Code comments SHOULD describe the why, not the how. Code should be
+  readable enough that it should be unnecessary to describe how it
+  works. Comments/JavaDoc should be used as applicable to put code in
+  context, providing the necessary information to understand why the
+  code does what it does.
+
+- Trivial JavaDoc should be avoided. In particular empty templates
+  that merely state what one can learn from the method signature
+  should be avoided.
+
+  Every class and interface SHOULD have detailed JavaDoc at the
+  class/interface level (detailed means more than a single line).
+
+  Method and field level JavaDoc SHOULD be used if applicable.
+
+
+- When using third party libraries, limit your choice to active
+  projects. Abandoned libraries should be replaced.
+
+  When using third party libraries, try to use it consistently and
+  throughout the code base. Go through the existing code and replace
+  our code with library code when applicable.
+
+  When using a third party library, use the library for the intended
+  purpose. Do not import a big library provinding unrelated
+  functionality just to gain access to a small utility class that
+  happens to be part of the library (besides introducing bloat, the
+  utility class is unlikely to survive if it isn't the main purpose of
+  the library). Consider contacting the author of the third party
+  library and ask them to split the needed functionality out into a
+  separate library.
+
+
+- Make your code DRY: Don't Repeat Yourself. 
+
+  The same is true for Maven project files.
+
+- Follow established conventions unless you have a good argument not
+  to.
+
+  In particular Maven encourages convention over configuration, so
+  stop fighting Maven and do it the Maven way.
+
+- Keep an eye on static analysis tools like PMD, FindBugs and IntelliJ.
+
+  It should not be a goal to push the list of warnings/errors down to
+  zero (the tools have plenty of false positives), but it is worth
+  going through the list from time to time and in particular fix all
+  high priority issues.
+
+- Read "The Pragmatic Programmer" and learn. 
+
+  Read the Gang of Four "Design Patterns" book and stop overusing the
+  patterns.
+
+
+