Truths which we believe to be self-evident (adapted from TextSecure’s)
-
The answer is not more options. If you feel compelled to add a preference that’s exposed to the user, it’s very possible you’ve made a wrong turn somewhere.
-
There are no power users. The idea that some users "understand" concepts better than others has proven to be, for the post part, false. If anything, "power users" are more dangerous than the test, and we should avoid exposing dangerous functionality to them.
-
If it’s "like PGP," it’s wrong. PGP is our guide for what not to do.
-
It’s an asynchronous world. We wary of anything that is anti-asynchronous: ACKs, protocol confirmations, or any protocol-level "advisory" message.
-
There is no such thing as time. Protocol ideas that require synchronized clocks are doomed to failure.
-
To the largest extent possible, all fields shall be private. Use an IDE to generate the getters and setters.
-
If a class has more than one
volatile
member field, it is probable that there are subtle race conditions. Please consider where appropriate encapsulation of the multiple fields into an immutable value object replace the multiplevolatile
member fields with a singlevolatile
reference to the value object (or perhaps better yet anAtomicReference
to allow forcompareAndSet
- if compare-and-set logic is appropriate). -
If it is
Serializable
it shall have aserialVersionUID
field. Unless code has shipped to users, the initial value of theserialVersionUID
field shall be1L
.
The project relies on [https://github.com/diffplug/spotless/tree/main/plugin-maven](the Spotless Maven Plugin) to manage its formatting.
The [https://github.com/google/google-java-format](google-java-format) project was chosen, check it, it contains links to plugins for various IDEs.
You can also run the formatter from command line: mvn spotless:apply
.
-
"hungarian"-style notation is banned (i.e. instance variable names preceded by an 'm', etc)
-
If the field is
static final
then it shall be named inALL_CAPS_WITH_UNDERSCORES
. -
Start variable names with a lowercase letter and use camelCase rather than under_scores.
-
Spelling and abbreviations: If the word is widely used in the JVM runtime, stick with the spelling/abbreviation in the JVM runtime, e.g.
color
overcolour
,sync
oversynch
,async
overasynch
, etc. -
It is acceptable to use
i
,j
,k
for loop indices and iterators. If you need more than three, you are likely doing something wrong and as such you shall either use full descriptive names or refactor. -
It is acceptable to use
e
for the exception in atry…catch
block. -
You shall never use
l
(i.e. lower caseL
) as a variable name.
-
For code in
src/main
:-
*
imports are banned. -
static
imports are strongly discouraged. -
static
*
imports are discouraged unless code readability is significantly enhanced and the import is restricted to a single class.
-
-
For code in
src/test
:-
*
imports of anything other than JUnit classes and Hamcrest matchers are banned. -
static
imports of anything other than JUnit classes and Hamcrest matchers are strongly discouraged. -
import static org.hamcrest.Matchers.
,import static org.junit.Assert.
,import static org.junit.Assume.
are expressly encouraged and permitted. Any otherstatic
imports are discouraged unless code readability is significantly enhanced and the import is restricted to a single class.
-
-
Each class shall have a Javadoc comment.
-
Each field shall have a Javadoc comment.
-
Unless the method is
private
, it shall have a Javadoc comment. -
When a method is overriding a method from a super-class / interface, unless the semantics of the method have changed it is sufficient to document the intent of implementing the super-method’s contract with:
/** * {@inheritDoc} */ @Override
-
Getters and Setters shall have a Javadoc comment. The following is preferred
/** * The count of widgets */ private int widgetCount; /** * Returns the count of widgets. * * @return the count of widgets. */ public int getWidgetCount() { return widgetCount; } /** * Sets the count of widgets. * * @param widgetCount the count of widgets. */ public void setWidgetCount(int widgetCount) { this.widgetCount = widgetCount; }
-
When adding a new class / interface / etc, it shall have a
@since
doc comment. The version shall beFIXME
to indicate that the person merging the change should replace theFIXME
with the next release version number. The fields and methods within a class/interface (but not nested classes) will be assumed to have the@since
annotation of their class/interface unless a different@since
annotation is present.
This library has a set of integration tests in the class src/test/java/org/zendesk/client/v2/RealSmokeTest.java
. These tests are used to validate the API calls with a real Zendesk instance. The project never got access to a specific sandbox provided by @zendesk thus we are using the sandbox used by CloudBees.
Some of these tests are sadly relying on some specific data of this instance (ex: https://github.com/cloudbees-oss/zendesk-java-client/blob/master/src/test/java/org/zendesk/client/v2/RealSmokeTest.java#L102-L103) and thus you cannot expect to execute all of them in a different instance.
To execute these tests you have to pass several settings in the file src/test/resources/zendesk.properties
:
url=#A ZENDESK SANDBOX URL#
username=#A EMAIL OF AN ACCOUNT HAVING ACCESS TO THE INSTANCE#
password=#THE PASSWORD OF THE ACCOUNT#
token=#A TOKEN TO ACCESS TO THE INSTANCE#
requester.email=#A EMAIL - can be like username - TO CREATE THE REPORTER#
requester.name=#A NAME FOR THE REPORTER#