``A computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read, and only incidentally for machines to execute.'' The Structure and Interpretation of Computer Programs, H. Abelson, G. Sussman and J. Sussman, 1985.
Contents
This page describes the Java and HTML coding styles for GATE (and the structure of the source and Web server trees). Note that this style applies to the GATE codebase; you don't need to use this style for external resources if you don't want to (but it would probably be a good idea if you did).
Java code style
Every bit of Java code in GATE should look like the following example. (Note that "like" does NOT mean "sort of kind of fairly similar".)
Notes:
- Break lines before 80 characters.
- Use 2-space indents in Java code, and follow the same style as the existing codebase.
- Put a CVS ID flag in each file. Start each file with the standard header.
- Make a javadoc comment on every class member, inc. private members.
- Where appropriate (almost always!) use the Java collections library for collections.
Debugging policy: if you want to debug a class using print statements and so on, add this member:
/** Are we debugging? */ private static final boolean DEBUG = false;then do stuff like
if(DEBUG) {
Out.pr("your debug stuff");
}
Remember to set the variable false before you check in.
Code example (read this in a fixed-width font).
/*
* DataStoreRegister.java
*
* Copyright (c) 1998-2001, The University of Sheffield.
*
* This file is part of GATE (see http://gate.ac.uk/), and is free
* software, licenced under the GNU Library General Public License,
* Version 2, June 1991 (in the distribution as file licence.html,
* and also available at http://gate.ac.uk/gate/licence.html).
*
* Hamish Cunningham, 23/Jan/2001
*
* $Id: codestyle.html,v 1.3 2002/01/19 15:05:20 hamish Exp $
*/
package gate;
import java.util.*;
import java.net.*;
import gate.util.*;
import gate.persist.*;
import gate.event.*;
/**
* Records all the open DataStores.
*/
public class DataStoreRegister extends HashSet {
/**
* All the DataStore classes available. This is a map of class name
* to descriptive text.
*/
public static Map getDataStoreClassNames() {
Map names = new HashMap();
// no plugability here at present.... at some future point there should
// be a capability to add new data store classes via creole.xml metadata
// and resource jars
names.put(
"gate.persist.SerialDataStore",
"SerialDataStore: file-based storage using Java serialisation"
);
return names;
} // getDataStoreClassNames()
/**
* Adds the specified element to this set if it is not already
* present. Overriden here for event registration code.
*/
public boolean add(Object o) {
return super.add(o);
} // add
/**
* Removes the given element from this set if it is present.
* Overriden here for event registration code.
*/
public boolean remove(Object o) {
boolean res = super.remove(o);
if(res) fireDatastoreClosed(
new CreoleEvent((DataStore)o, CreoleEvent.DATASTORE_CLOSED)
);
return res;
} // remove
/**
* Removes all of the elements from this set.
* Overriden here for event registration code.
*/
public void clear() {
Set datastores = new HashSet(this);
super.clear();
Iterator iter = datastores.iterator();
while(iter.hasNext()) {
fireDatastoreClosed(
new CreoleEvent((DataStore) iter.next(), CreoleEvent.DATASTORE_CLOSED)
);
} // while
} // clear()
......
} // class DataStoreRegister
HTML code style
Notes:
- Break lines before 80 characters.
- Use 2-space indents. Indent tables so they're meaningful.
- Put markup on separate lines to make things clearer (e.g. in lists).
- If you use complex HTML you must: explain it in comments; make sure it runs on recent Netscape and IE; think about the implications for people who e.g. have vision problems and may not be able to get a speech generator to read your page; think about how long the page will take to go down a modem link.
- Put a CVS ID flag in each file. Start each file with a header that includes meaningful title.
- Always use size tags for images, so that the browser can display the rest of the page while waiting for the image to load. (You can use this script to generate size tags.)
(Read this in a fixed-width font).
<P>
GATE is a domain-specific software architecure and development environment
that supports:
<UL>
<LI>
researchers in Natural Language Processing and Computational Linguistics
<LI>
developers who are producing and delivering
<A HREF=http://www.dcs.shef.ac.uk/~hamish/thesis/le.html>Language
Engineering</A> systems.
</UL>
<P>
The GATE distrubution includes a free
<A HREF="http://www.dcs.shef.ac.uk/nlp/extraction/">Information
Extraction</A> system, which is free for all research purposes.
<P>
<TABLE BORDER=1>
<TR>
<TD>
<B>Introduction</B>
<BR>
</TD>
<TD>
<A HREF=http://www.dcs.shef.ac.uk/~hamish/GateIntro.html>A
non-technical introduction</A>
</TD>
<TD>
<A HREF=architecture.html>Some more technical details</A>
</TD>
<TD>
<A HREF=publications.html>Links to publications</A>
</TD>
</TR>
<TR>
<TD>
<B>Download</B>
<BR>
</TD>
<TD>
To download, you first need to
<A HREF=registration/reg-form.html>register here</A>,
</TD>
<TD>
and a password will be emailed to you;
</TD>
<TD>
then go to <A HREF=software.html>the download page</A>.
</TD>
</TR>
<TR>
<TD>
<B>Documentation</B>
<BR>
</TD>
<TD>
<A HREF=system_docs/gate_docs.html>System manuals</A>
</TD>
<TD>
<A HREF=news.html>Known bugs</A>
</TD>
<TD>
<A HREF=tipster.html>The TIPSTER architecture</A>
</TD>
</TR>
<TR>
<TD>
<B>Misc</B>
<BR>
</TD>
<TD>
<A HREF=users.html>Users of GATE</A>
</TD>
<TD>
<A HREF=people.html>The people involved</A>
</TD>
<TD>
<A HREF="http://www.dcs.shef.ac.uk/nlp/gate/contrib/michael.dorna/">A
tutorial in German</A>
</TD>
</TR>
</TABLE>
Notes on the structure of the source tree and web servers
The tree looks like this:
gate/build home of makefiles and scripts, and gate.jar gate/classes .class, resource and .tcl files gate/doc documentation gate/doc/internal stuff we don't release, e.g. design notes gate/doc/javadoc autogenerated javadoc stuff gate/doc/javadoc/internal javadoc stuff including private members gate/lib .jars, .zips and associated licences gate/misc misc stuff like example jape grammars gate/src the source code gate/src/gate/resources resources (NOT CREOLE resources, Java resources!) which get copied into the classes directory (and gate.jar) gate/src/gate/resources/gate.ac.uk resources that get copied to the web servers
Web servers:
- http://gate.ac.uk/ is the production server
- http://derwent.dcs.shef.ac.uk/ is the solaris development server; a full copy of gate.ac.uk is in http://derwent/gate.ac.uk/
- http://redmires/ is the linux development server, with lots of Java and tool documentation
Derwent and gate.ac.uk both serve files used by the test suite, and also any CREOLE metadata or GATE config data that we may want to distribute centrally. These files are also available in the resources tree. Some important files are:
creole/creole.xml a central CREOLE metadata file tests/creole.xml a file for TestCreole tests tests/gate.xml a file for TestConfig tests
These are copied onto the web servers and live in:
gate/src/gate/resources/gate.ac.uk/creole/creole.xml gate/src/gate/resources/gate.ac.uk/tests/creole.xml gate/src/gate/resources/gate.ac.uk/tests/gate.xml
Not on the web servers, but in gate/classes and gate.jar:
gate/resources/creole/creole.xml CREOLE metadata file for builtins gate/resources/gate.xml central configuration data
Which live in:
gate/src/gate/resources/creole/creole.xml gate/src/gate/resources/gate.xml
The resources tree, the test suite and the web servers all interconnect, so that a) we can maintain the server files under CVS and b) we can have the test files in gate/classes and in gate.jar so we can run tests even when there is no web server accessible. The CVS version of the tests and central CREOLE metadata is all kept in the resources tree. Those under gate/src/gate/resources/gate.ac.uk are copied into locations on derwent by the nightly build script.
