Various developers have been working on the OMERO project for up to 5 years. Each time the team growsa, we are reminded that the project’s development practices must be more mature and transparent. The initial learning curve for new developers must be minimized.
In order for any of the aforementioned goals to be achieved there must be better communication, better division of work and better management and ownership of certain parts of the codebase.
These ideals are not just a function of project size, but a culmination of factors including: geographically disperse developers (at least 9 time zones), increasing numbers of new developers, complexity of our code base and the sheer amount of commit activity. In addition, we have also seen increasing numbers of external developers who want to plug-in to OME technology, maintainership gives them a clear understanding of who to come to for support and direction.
There is absolutely nothing worse or more infuriating than attempting to review or look at messy code. Messy code is an absolute pain to debug or review and just shows disrespect for other developers time. In short:
All sounds rather vague doesn’t it? What about <insert specific question here>?
Well, we will have a house set of coding style guidelines that everyone will adhere to without exceptions; you are not developing Perl scripts in your basement to sort photos of your grandmother. This house set of style guidelines will evolve over the next few weeks. People are welcome to speak up for things that they would prefer or pet peeves that they have. I will be pulling general wisdom from the following:
First versions of our coding styles are available from git at:
Eventually all code will be formatted using these settings and the Eclipse 3.1+ formatter. Because the OMERO Java and Python source files are encoded in UTF-8, ensure that the encoding in Eclipse (Preferences ‣ General ‣ Workspace ‣ Text file encoding) is also set to UTF-8. A policy of UTF-8 encoding for C++ source files is under consideration, along with instructions for configuring MSVC accordingly.
Security is a both a personal interest of mine (Chris) and something that I believe to be extremely important in software design. Moving to a new set of frameworks and technology also gives us an opportunity to rethink some of our priorities, security in particular. For almost the duration of the OME project, security practices (access control, user management, database authentication, etc.) have been poor or non-existent. Now is the time to change that. Over the next few weeks I will be adding to this page relevant talks and suggestions as well as integrating these concepts into the code style guide.
For now, a few talks (okay... just one for now) from some Java security professionals:
Marc Schoenefeld
Without good communication, all the other concepts fall down. To this end, several weekly or monthly conference calls are arranged to report on status. See Conference calls for times and login information.
For information on team communication and process see OME Team Developer Practices.
Maintain a list of contributors, similar to contributors.
When a script is submitted:
Script approved by <name of team member who validates> on <date>.
Tested on OMERO <version. Script behaves as described.
Expected to work on all <version> servers.
Merge or Integrate a patch:
When fixing a problem:
At present, there are uses of System.out.println throughout the code base. These are being removed. Apache logging is used and should be throughout and consistently. Also, the following should NOT be used.
log.debug("My output text");
The log statements should be wrapped with checking logic for appropriate warning LEVEL configuration. This is done like so.
if (log.isDebugEnabled()) {
log.debug("My output text will work if debug LEVEL logging is on.");
}
When your logging statements are wrapped, all logging can be turned on or off very easily in the configuration file(s). Before you can use a logger you will need to declare one at the top of each class like so.
private static Log log = LogFactory.getLog(YourSpecificClassName.class);
As we all know, the easy thing to do in a catch block is to use the printStackTrace method. Do not leave these. We are removing these and replacing them with something similar to this below.
catch (IOException ioex) {
log.error("Could not write to file", ioex);
}
The getCause() method is used to pass the Throwable exception to the log. Any stacktrace output will be sent to the log. Please remember that sometimes a new Exception is thrown, possibly to support the method or a ResourceError is created. The ResourceError is handled like so.
catch (IOException e)
{
log.error("Could not read from file", e);
throw new ResourceError(e.getMessage() + " Please check server log.");
}
This list was initially a starting point for discussion for the September 2008 Dundee Developers meeting:
The following topics are all completely open for anyone to add or veto (please don’t delete). Some we already do, some are highly questionable. It is also unlikely that we would even be able to implement all such “standards” at once, but it would be good to have some guidelines as well as a list of things we would like to try for moving forward.
See Agile Adoption Practices, Elssamadisy
a: As for September 2008, roughly a dozen developers were working on OMERO.