Coding convention

From Endrov

Contents

Indentation rules

Wishart indent. Example:

public static class Foo
	{
	private static List<Class<?>> getRelatedClasses(Class<?> c)
		{
		LinkedList<Class<?>> list=new LinkedList<Class<?>>();
		for(Class<?> x:c.getInterfaces())
			list.add(x);
		Class<?> sup=c;
		while(sup!=Object.class)
			{
			list.add(sup);
			sup=sup.getSuperclass();
			}
		list.add(Object.class);
		return list;
		}
	}

Indentation settings for Eclipse

Module files may used other indentation if they are well isolated. If there is a need to overhaul the code in one of these files it may be reformatted to wishart however.

Naming convention

  • Standard Java naming convention: methodsInClasses, ClassNames.
  • Whenever possible, classes should be named in such a way that auto-complete (ctrl+space in eclipse) can be used to browse the classes in an easy way
  • Specific case: Non-abstract image operation classes should always start with EvOp
  • Specific case: Flow unit classes should always start with FlowUnit
  • Do not pollute the namespace. Avoid using a name of a class that has been used before.

Visibility

There is no visibility fascism in this project

  • Let variables be public if you want to
  • Do use private when you know it's a variable that shouldn't be touched by other users, in particular if you think it might be changed later
  • Variables need not have get/set-methods, but if you suspect that the behaviour of a variable or class will be changed later then this is encouraged

Anonymous classes and classes declared in classes

No restriction whatsoever on use. On the contrary, do not hesitate to use them:

  • Swing listeners are usually best off as anonymous classes. Inheritance might be a problem otherwise if you put the listener method in the widget class
  • Anonymous classes cannot pollute the namespace
  • Classes declared in other classes are hidden from auto-complete unless the user steps into the parent class. This minimizes namespace pollution.

Java and machine

Assume Java 1.5. Code should work with OpenJDK. Supported platforms are at minimum Linux, Mac and Windows. If code can be written to be 100% platform agnostic then this should be the goal. We should demand good support for Java on the platform. If there are quirks then we should avoid patching it on our side. If a platform end up too crippled to run Java then we should rather drop that platform than letting us be held back from further development.

OpenGL

  • OpenGL 2.1 is assumed at the moment
  • If possible, write code that easily translates into OpenGL 3.1

JNI and invoking programs from the console

This breaks easy portability. Should be avoided at all cost. If possible, do the community a favour and convert the library to Java, or write a Java-equivalent.

If you do use JNI to access a library, please consider making a separate project just to maintain the wrapper, with compiled binaries for all platforms.

Same rules apply for invoking programs from the console.

Optimization

  • Always give thought to what data structures to use. HashMap/HashSet are faster than TreeMap/TreeSet whenever they can be used. LinkedList has faster add() than Arraylist. Feel free to ask for advice if this is new for you.
  • Try to use optimal or near-optimal algorithms for heavier operations, image processing in particular. Document the complexity in the comment for the function and state if it can be improved further. This will prove useful for other users when they are optimizing their code; they will know if a function they rely on can be made faster or if they should look somewhere else.
  • Algorithms which in turn might be used by other algorithms are higher priority than code aimed at a very small group of users

Assume small community

Do not optimize the code for many monkeys. A small group of people will maintain it.

  • Maximize code reuse unless speed motivates longer code
  • Do not add complicated build procedures
  • Use metaprogramming if you need to template code

Long-term maintainability is always priority #1.