<!--

Chapter on best practices for the DrJava Developer Documentation. All

chapters are joined into a single document in devdoc.docbook.

@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $

-->

<chapter id="bestPractices">

<title>Development Best Practices</title>

<para>[TODO]</para>

</chapter>

<!--

Introductory chapter for the DrJava Developer Documentation. All

chapters are joined into a single document in devdoc.docbook.

@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $

-->

<chapter id="introduction">

<title>Introduction</title>

<para>This document is primarily intended as an orientation resource and collection of acquired knowledge for Rice students working as DrJava developers. As an open-source project, DrJava's source code is also available for browsing and modification to the general public, and so the following will also serve to provide those interested with the necessary tools to build, fix, and improve the code base. (Although we do not usually provide direct CVS commit access to individuals outside the Rice development team, interested parties are welcome to submit changes via the SourceForge Tracker forums.)</para>

<section>

<title>Overview</title>

<para>We cover the following topics:

<itemizedlist>

<listitem><para><link linkend="introduction">Introduction</link> provides a high-level sense of purpose and history for the DrJava project.</para></listitem>

<listitem><para><link linkend="gettingStarted">Getting Started</link> describes how to set up and use the essential tools required to build and modify the DrJava source code.</para></listitem>

<listitem><para><link linkend="supportingTechnology">Supporting Technology</link> provides a more in-depth guide to a variety of third-party technologies (applications and libraries) used to build and run DrJava.</para></listitem>

<listitem><para><link linkend="systemArchitecture">System Architecture</link> provides a high-level view of the DrJava sources. It describes the code organization and discusses various significant design decisions.</para></listitem>

<listitem><para><link linkend="bestPractices">Development Best Practices</link> describes the coding and testing standards we maintain (or aspire to) in the DrJava code base.</para></listitem>

<listitem><para><link linkend="projectAdministration">Project Administration</link> contains instructions directed at project administrators. It covers, for example, making official DrJava releases and maintaining the project Web site.</para></listitem>

</itemizedlist>

</para>

</section>

<section>

<title>Project Philosophy</title>

<para>DrJava is a lightweight, powerful Java development environment. Its target audience includes both beginning Computer Science students and advanced professional users. Clearly, there is a tension between these goals &mdash; "lightweight" versus "powerful"; "beginning" versus "advanced." This tension is generally resolved by <emphasis>insuring</emphasis> the prior conditions &mdash; that DrJava be easy to use and inobtrusive for beginners &mdash; and adding "advanced" features only if they can be presented in a simple, lightweight (both in terms of system resources and user interface) manner. The interactions pane is an ideal example of a nice marriage between the goals of simplicity and power. It is easy for beginners to understand and use &mdash; in fact, it's where many beginners get their first taste of Java programming. Yet professional developers also find it quite handy, and sometimes lament the lack of something like it in heavier-weight IDEs.</para>

<para>Because DrJava was originally conceived as a teaching tool, and because it has been almost entirely developed by undergraduate and graduate students, it is uniquely positioned to address the needs of students, teachers, and researchers. We hope that this fount of experience will translate into a relevant, useful, and unique product. However, development on the project is at a relative disadvantage due to the lack of a full-time or long-term workforce. These challenges are addressed by maintaining a self-documenting, self-testing code base. Developers should keep in mind that the code they write will be browsed and modified subsequently by many others, and if the reasoning behind the code is not documented by comments and tests, it will probably be lost.</para>

<para>Finally, DrJava is open source software. [TODO: discuss; explain the DrJava license]</para>

</section>

<section>

<title>Project History</title>

<para>[TODO]</para>

</section>

</chapter>

<!--

Project admin chapter for the DrJava Developer Documentation. All

chapters are joined into a single document in devdoc.docbook.

@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $

-->

<chapter id="projectAdministration">

<title>Project Administration</title>

<para>[TODO]</para>

<!-- Clipped from the previous docs:

<para>It is important to update the DrJava website after all changes to the documentation. This involves copying the HTML files for the user, quickstart, and developer documentation (and the PDF file for the user documentation) to <filename>drjava.sf.net:/home/groups/d/dr/drjava/htdocs/</filename>. The HTML files should go in the <filename>userdocs/</filename>, <filename>quickstartdocs</filename>, and <filename>devdocs/</filename> directories, respectively, while the PDF should be saved as <filename>drjava-userdoc.pdf</filename> directly in <filename>htdocs/</filename>.</para>

-->

</chapter>

<!--

Chapter covering supporting technology in the DrJava Developer

Documentation. All chapters are joined into a single document

in devdoc.docbook.

@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $

-->

<chapter id="supportingTechnology">

<title>Supporting Technology</title>

<para>This section is intended as a repository of acquired knowledge with respect to the ins and outs of supporting technology used with DrJava. For each tool or library, a section will address questions like:

<itemizedlist>

<listitem><para>How is this technology used in the DrJava code base or build process?</para></listitem>

<listitem><para>How is the technology distributed; what needs to be done to install it?</para></listitem>

<listitem><para>Do we depend on a specific version of the software?</para></listitem>

<listitem><para>What are the key options or classes that developers should be aware of?</para></listitem>

<listitem><para>Where can more comprehensive documentation be found?</para></listitem>

<listitem><para>Why has this particular technology been chosen? What are the alternatives?</para></listitem>

</itemizedlist>

</para>

<section id="java">

<title>Java Language & APIs</title>

<para>[TODO]</para>

</section>

<section id="javac">

<title><command>javac</command></title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installJDK">JDK installation instructions</link> for installation details -->

</section>

<section id="javadoc">

<title><command>javadoc</command></title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installJDK">JDK installation instructions</link> for installation details -->

</section>

<section id="rmi">

<title>RMI</title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installJDK">JDK installation instructions</link> for installation details -->

</section>

<section id="jpda">

<title>JPDA</title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installJDK">JDK installation instructions</link> for installation details -->

</section>

<section id="subversion">

<title>Subversion</title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installSubversion">Subversion installation instructions</link> for installation details -->

<!-- Should include instructions on moving and adding files, and on tagging and branching -->

<!-- Clipped from the previous docs:

<para>If you will be adding new files as part of your commit, you will need to first let the CVS server know that the new files exist. Run "<literal>cvs add [FILE]</literal>" for each new file that you will be adding before running <literal>ant commit</literal>. Also, it is very important that you copy the license comment from another file into your new file. We also prefer that you include a "<literal>@version &#36;Id&#36;</literal>" tag in your class-level Javadoc comment, which helps us note the last time the file was modified.</para>

-->

</section>

<section id="ant">

<title>Ant</title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installAnt">Ant installation instructions</link> for installation details -->

</section>

<section id="junit">

<title>JUnit</title>

<para>[TODO]</para>

<!-- We can point to the <link linkend="installJUnit">JUnit installation instructions</link> for installation details -->

</section>

<section id="SourceForge">

<title>SourceForge</title>

<para>[TODO]</para>

</section>

<section id="clover">

<title>Clover</title>

<para>[TODO]</para>

</section>

<section id="retroweaver">

<title>Retroweaver</title>

<para>[TODO]</para>

</section>

<section id="docbook">

<title>DocBook</title>

<para>[TODO]</para>

<!-- Clipped from the previous docs:

Beware that some versions of these tools may not work with our build script or may generate HTML files without an <filename>index.html</filename> file. (If this is the case, as it is currently on the greenland server, you'll probably want to copy <filename>book1.html</filename> to <filename>index.html</filename>. Don't just rename it, because other files will link to the old one.)

-->

</section>

<section id="javacc">

<title>JavaCC</title>

<para>[TODO]</para>

</section>

<section id="bcel">

<title>BCEL</title>

<para>[TODO]</para>

</section>

<section id="otherTools">

<title>Other Useful Development Tools</title>

<para>[TODO]</para>

<section id="findbugs">

<title>FindBugs</title>

<para>[TODO]</para>

</section>

<section id="x11">

<title>X11</title>

<para>[TODO]</para>

<!-- This can contain tips and guidance on building remotely using X11 -->

<!-- Clipped from the previous docs:

<para>If you are running the tests on Windows over an SSH connection to a Unix server, you will need to have an X server running (such as X-Win32), and you will need to enable "X11 Tunneling" in the preferences of your SSH client. This is because Swing components will be created in the tests, which require an X server even if they are not explicitly shown.</para>

-->

</section>

<section id="eclipse">

<title>Eclipse</title>

<para>[TODO]</para>

<!-- This can contain tips on how to use some of Eclipse's features - how to use it as the IDE, taking advantage of its extensive compiler warnings, etc. -->

</section>

</section>

</chapter>

<!--

Chapter describing system architecture in the DrJava Developer

Documentation. All chapters are joined into a single document

in devdoc.docbook.

@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $

-->

<chapter id="systemArchitecture">

<title>System Architecture</title>

<para>[TODO]</para>

<!-- Clipped from the previous docs (for the description under the "docs" module):

<para>Emacs and modern versions of KDE's KWrite are both good editors for DocBook files. Please try to maintain a consistent style within the documentation, both in tone (eg. somewhat informal &mdash; "you" instead of "the user") and formatting (eg. literal tags for small bits of code, paragraphs on one line, etc).</para>

-->

<!-- Also clipped from the previous docs:

<formalpara>

<title>Use of the Configuration Framework</title>

<para>DrJava's configurable options are managed through a framework in the <literal>edu.rice.cs.drjava.config</literal> package. This framework takes care of loading and saving options from the <filename>.drjava</filename> file, as well as managing listeners to changed configuration options. The main class of interest is <literal>OptionConstants</literal>, which defines all options and their default values. You can get and change settings using the static <literal>DrJava.getConfig()</literal> method.</para>

</formalpara>

<para>It is very important never to use the configuration framework in the Interpreter JVM, since this will instantiate a new copy of the framework inconsistent with the one in the Main JVM. (It also causes the "SlaveJVMRunner" icon to appear in Mac OS X.) It is also very important never to use the configuration framework in the Eclipse plug-in, because it causes Eclipse to crash. (We're not sure why, but it's better for us to use Eclipse's preferences in that world anyway.)</para>

-->

</chapter>