Here we will be adding examples of good code, if you want to add somethings, please talk with the integrators first.
* Example for good equals method.
* You can use the mouse-right-button menu in the source code area of eclipse -> Source -> "Generate hashCode() and equals()..." for template, but refactor it to look like the example bellow:
{{{
@Override
public boolean equals(Object object) {
if (object == null) {
return false;
}
if (object == this) {
return true;
}
if (object.getClass() != this.getClass()) {
return false;
}
// Custom code here...
}
}}}
* Writing if, else, else if, for, while, do while, try, catch, finally statements, blocks.
* First of all always put curly brackets after the special word that opens the statement, even if the statement contains one row.
{{{
if (some_condition) {
System.out.println("pass");
}
}}}
* Insert spaces between the brackets and the words. The opening bracket of a statement is on the row where the statement is!
{{{
while (some_condition) {
// something...
}
}}}
* When writing conditions put spaces between the operands and the operators!
{{{
if (a != b) {
System.out.println("a is not the same as b");
}
}}}
* if-else if- else example:
{{{
if (a != b) {
// something...
} else if (c != d) {
// other thing...
} else if ((b == c) && (a == d)) {
// third thing, I put the brackets for easier reading, they are not mandatory.
} else {
// four...
}
}}}
* for examples
{{{
for (i = 0; i < n; i++) {
// do something...
}
}}}
{{{
for (Some_iterable_type some_var : some_iterable) {
// do something...
}
}}}
* try-catch-finally... The same as the above as spacing and etc...
{{{
try {
// some code
} catch (Exception e) {
// handle exception
} finally {
// some stuff
}
}}}
* Don't use @SuppressWarnings("all") and @SuppressWarnings("synthetic-access") at all, other like @SuppressWarnings("synthetic-access"), @SuppressWarnings("unchecked"), etc.. you can use, but rarely only when needed!
* We don't have special conventions for naming but don't use long name or stupid ones like "stuff".
* Don't leave commented code where you tried something to be reviewed, we will be not very happy.
* Avoid writing expressions on several lines, instead use variables... but if it's needed for example in statements here are some examples :
* Write {{{ && and || }}} to be first on the new line.
{{{
a == b
&& c == d
|| b != g
&& !flag
}}}
* If you Ctrl+Shift+F, please refactor your code not to have something like:
{{{
res
.setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE);
}}}
to something like
{{{
res.setDefaultCloseOperation(
WindowConstants.DO_NOTHING_ON_CLOSE);
}}}
but again it is advisable to use variables, something like:
{{{
int closeOperation = WindowConstants.DO_NOTHING_ON_CLOSE;
res.setDefaultCloseOperation(closeOperation);
}}}
* Writing tests:
* Write tests that test something you wrote, not the JDK
* The tests are code, so all the above rules apply to them.
* You can use the template for tests in Eclipse, write the word test -> ctrl+space -> choose the "test - test method" template from the auto-complete menu.
* Our tests extend either UnitTestBase, either IntegrationTestBase.
* Put @After, @Before and @Test annotations.
* The first thing in a setUp method is calling the super.setUp() method, the last thing in a tearDown method is calling the super.tearDown() method.
* Example for good test:
{{{
package org.sophie2.base.commons.util.position;
import junit.framework.AssertionFailedError;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;
import org.sophie2.core.testing.UnitTestBase;
/**
* Unit test for {@link ImmVector}.
*
* @author Pap
*/
public class ImmVectorTest extends UnitTestBase {
@Override
@Before
protected void setUp() throws Exception {
super.setUp();
}
@Override
@After
protected void tearDown() throws Exception {
super.tearDown();
}
/**
* Tests getters of {@link ImmVector}.
*/
@Test
public void testGetters() {
float x = 5.0f;
float y = 10.0f;
float t = 2.0f;
ImmVector v = new ImmVector(x, y, t);
assertEquals(x, v.getX());
assertEquals(y, v.getY());
assertEquals(t, v.getT());
assertEquals(x / t, v.getPointX());
assertEquals(y / t, v.getPointY());
}
/**
* Tests {@link ImmVector#add(ImmVector)}.
*/
@Test
public void testAdd() {
ImmVector vec1 = new ImmVector(10.0f, 10.0f);
ImmVector vec2 = new ImmVector(5.0f, 20.0f);
ImmVector expected = new ImmVector(15.0f, 30.0f);
assertEquals(expected, vec1.add(vec2));
}
/**
* Tests {@link ImmVector#dotProduct(ImmVector)}.
*/
@Test
public void testDotProduct() {
ImmVector vec1 = new ImmVector(1.0f, 1.0f, 0);
ImmVector vec2 = new ImmVector(-1.0f, 1.0f, 0);
float res = vec1.dotProduct(vec2);
float expected = 0f;
assertEquals(expected, res);
}
/**
* Tests whether {@link ImmRect} is immutable.
*/
@Test
public void testImmutable() {
ImmVector v1 = new ImmVector(10.0f, 5.0f, 2.0f);
ImmVector v2 = v1;
assertSame(v1, v2);
ImmVector result = v1.add(new ImmVector(0, 0, 1));
assertNotSame(v1, result);
assertTrue(v1.equalsHomogeneously(result));
assertSame(v1, v1);
}
/**
* Tests {@link ImmVector#equalsHomogeneously}.
*/
@Test
public void testEqualsHomogeneouslyVectors() {
ImmVector v1 = new ImmVector(10, 10, 0);
ImmVector v2 = new ImmVector(20, 20, 0);
assertTrue(v1.equalsHomogeneously(v2));
ImmVector v3 = new ImmVector(10, 15, 0);
assertFalse(v1.equalsHomogeneously(v3));
ImmVector v4 = new ImmVector(10, 10, 1);
ImmVector v5 = new ImmVector(20, 20, 2);
assertTrue(v4.equalsHomogeneously(v5));
ImmVector v6 = new ImmVector(10, 10, 2);
assertFalse(v6.equalsHomogeneously(v4));
}
/**
* Tests {@link ImmVector#opposite()}.
*/
@Test
public void testOpposite() {
ImmVector vec = new ImmVector(10.0f, 10.0f);
ImmVector res = vec.opposite();
ImmVector expected = new ImmVector(-10.0f, -10.0f);
assertEquals(expected, res);
}
/**
* Tests that multiplication between a {@link ImmVector} and a
* {@link ImmPoint} is undefined.
*/
@Test
public void testDotProductVectorPoint() {
ImmVector point = new ImmVector(1.0f, 1.0f, 1.0f);
ImmVector vector = new ImmVector(1, 1, 0);
try {
point.dotProduct(vector);
fail();
} catch (Throwable t) {
if (t instanceof AssertionFailedError) {
fail();
}
}
}
/**
* Tests that a vector must not have all zero coordinates.
*/
@Test
public void testEqualsPointVector() {
ImmVector point = new ImmVector(1, 1, 1);
ImmVector vector = new ImmVector(1, 1, 0);
assertFalse(point.equals(vector));
}
/**
* Tests that a {@link ImmVector} cannot have all coordinates equal to zero.
*/
@Test
public void testAllZeroes() {
try {
new ImmVector(0, 0, 0);
fail();
} catch (Throwable t) {
if (t instanceof AssertionFailedError) {
fail();
}
}
}
}
}}}
* About the javadoc:
* Write good javadoc that describes classes, methods and variables
* Add yourself to the author list when you modify the logic, if your changes do not alter the logic don't do it.
* Write parameter descriptions on the next row.
* Write all the @parameter, @return, descriptions as a sentences which begin with upper case letter and end with a punctuation mark. Write the description itself of the javadoc even for getters and setters, write it as sentences!
* Examples:
* Method:
{{{
/*
* Moves the head position to a specified time in the timeline. If it
* exceeds the length of the timeline, the position is not changed.
*
* @param time
* The time to jump to (in seconds).
* @return
* The new head position.
*/
}}}
* Class:
{{{
/**
* A class representing a given aspect of a given {@link BasePro}.
* Currently used only with {@link BaseProList}s.
*
* {@link Aspect}s can be used by {@link BasePro}s internally to reduce the attached listeners
* and the registered reads.
*
* This way:
* 1) Some reads could be registered not with the {@link BasePro} itself but with an {@link Aspect}
* of the {@link BasePro}, and so potentially lots of listeners will be attached to the
* {@link Aspect}s, instead of the {@link BasePro}.
* 2) ProChanges will be fired from the {@link Aspect}s of the {@link BasePro} to registered
* listeners, instead of always firing from the {@link BasePro} itself.
*
* @author gogov
*/
}}}