Whitepapers

The KindSoftware Coding Standards

Table of Contents:

  1. Introduction
  2. Documentation
  3. Naming Conventions
  4. Semantic Properties
  5. Tools
  6. Code Examples
  7. References
  8. Specific Recommendations for:
    1. Java
    2. Eiffel
  9. Credits

Tools

(X)Emacs

The canonical summary: Emacs is the extensible, customizable, self-documenting real-time display editor.

(Rewritten from the XEmacs home page) Emacs is a powerful, extensible text editor with full GUI and terminal support.

Two primary supported free implementations of Emacs exist:

  • FSF Emacs, the Free Software Foundation's mainline Emacs implementation, and
  • XEmacs, a highly graphical version initially based on an early version of GNU Emacs 19 from the Free Software Foundation and since kept up to date with recent versions of that product. XEmacs stems from a collaboration of Lucid, Inc. with Sun Microsystems, Inc. and the University of Illinois, with additional support having been provided by Amdahl Corporation and Altrasoft.

Extending Emacs. (X)Emacs is extended through the use of Emacs Lisp packages. The primary packages we use for the development of Java are as follows. This list is by no means complete and reflects our personal biases. Some of the following summaries come directly from the info web pages for the corresponding package.

  • Semantic/Bovine. Semantic is a program for Emacs which includes, at its core, a lexer, and two compiler compilers (bovinator and wisent). Additional tools include, support for imenu, speedbar, whichfunc, eldoc, hippie-expand, and several other build in tools.

    The core utility is the parser infrastructure which allows different types of parsers to be linked into the system. Two build in parsers include the "bovine" parser, and the "wisent" parser.

  • Speedbar. Speedbar is a program for Emacs which can be used to summarize information related to the current buffer. Its original inspiration is the `explorer' often used in modern development environments, office packages, and web browsers.
  • EIEIO. Summary.
  • AucTeX. Summary.
  • Proof General. Summary.
  • Emacs Library (elib). Summary.
  • Tramp. Summary.
  • Wiki. Emacs-Wiki enables you to create and use hyperlinks and simple formatting in plain text files, and to optionally publish your pages as HTML.
  • Folding. This package provides a minor mode, compatible with all major editing modes, for folding (hiding) parts of the edited text or program.

    Folding mode handles a document as a tree, where each branch is bounded by special markers `{{{' and `}}}'. A branch can be placed inside another branch, creating a complete hierarchical structure.

  • Tracker. This mode keeps a list of projects and associated billing entity. A single project can be selected and it will be marked in a file as active until a new command is made to stop it. A project is automatically terminated when emacs exits. If somehow this fails, the tracking data file is touched at regular intervals, so the next time the tracker is started if there is an open project a reasonable guess can be made as to when to mark it as closed. Each session can have multiple comments associated with it, in which you can mark acomplishments or whatever. It will generate informal daily summary reports and a report of total hours for a particular billee.
  • Calendar and Diary. Emacs provides the functions of a desk calendar, with a diary of planned or past events. It also has facilities for managing your appointments, and keeping track of how much time you spend working on certain projects.
  • ECB (Emacs Code Browser). While (X)Emacs already has good editing support for many modes, its browsing support is somewhat lacking. That's where ECB comes in: it displays a number of informational windows that allow for easy source code navigation and overview.
  • Timeclock. This mode is for keeping track of time intervals. You can use it for whatever purpose you like, but the typical scenario is to keep track of how much time you spend working on certain projects.
  • Planner/Remember. Planner mode is an organizer and day planner for Emacs. It helps you keep track of your completed and pending tasks, daily schedule, and notes in plain text files. Planner mode is based on the aforementioned Emacs-Wiki mode.
  • EDE (Emacs Development Environment). EDE provides the gloss that simplifies the learning curve for all the very useful functionality of building and debugging under emacs. In doing so it attempts to emulate a typical IDE (Integrated Development Environment). What this means is that EDE will manage or create your makefiles and other building environment duties so the developer can concentrate on code, and not support files. In doing so, it will be much easier for new programmers to learn and adopt the GNU ways of doing things.
  • SLIME. SLIME is a major mode for programming in Common Lisp. It essentially replaces ILISP mode which is no longer wholly supported. SLIME works with all major variants of Common Lisp.

    SLIME uses a socket-based communication/RPC interface between Emacs and Lisp. Slime mode is a minor-mode complementing Lisp mode. It includes many commands for interacting with the Common Lisp process, including a a read-eval-print loop and a Common Lisp debugger written in Emacs Lisp. The debugger pops up an Emacs buffer similar to the Emacs/Elisp debugger.

  • CLHS/HyperSpec (Common Lisp HyperSpec). CLHS and HyperSpec are minor modes used to look up definitions in the ANSI Common Lisp standard (ANSI X3.226-1994) which is available on the web, courtesy of Kent Pitman and Xanalys.
  • X-Refactory. XRef is a cross referencing tool for C and Java. It lets you lookup definitions, uses of variables and functions, and refactor source code in a type-safe way.
  • Caml and Tuareg mode. These are two major modes for programming in (O)Caml. I prefer the former, but many people prefer the latter. It provides a read-eval-print loop, built-in support for compilation, debugging, and more.
  • Preview-LaTeX. This Elisp/LaTeX package will render your displayed LaTeX equations right into the editing window where they belong. The purpose of preview-latex is to embed LaTeX environments such as display math or figures into the source buffers. By mouse-clicking, you can open the original text. After editing, another click will just run the region in question through LaTeX and redisplay the new results.
  • W3M. Summary.
  • X-Symbol. This file documents X-Symbol, a package providing semi-WYSIWYG for LaTeX, HTML and other ``token languages''. It uses additional fonts and provide input methods to insert their characters into your document.
  • CC-mode. This is a GNU Emacs mode for editing files containing C, C++, Objective-C, Java, and CORBA IDL code. CC-mode support template insertion, auto-indenting, key shortcuts for often used expressions and blocks and much, much more. Documentation on cc-mode can be found in the info pages of your Emacs process (type control-h then 'i').
  • fill-paragraph. The fill-* functions reformat sections of text, code, etc. to be more readable. I.e. They can automatically reorganize and/or justify your code, text, HTML, etc. to fit your needs. The primary use of fill-paragraph while coding in Java is cleaning up documentation in comments. Most programmers do not like what it does to their source code by default.
  • The OO Browser. OOBR, the object-oriented browser, used to be a free piece of software from Bob Weiner. It is/was a very powerful, flexible, multi-language, source code browser (a la the Smalltalk tradition) for Emacs.
  • JDEE: The Java Development Environment for Emacs.: The JDEE is an Emacs Lisp package that provides a highly configurable Emacs wrapper for command-line Java development tools, such as those provided in JavaSoft's JDK. The JDEE provides menu access to a Java compiler, debugger, and API documenter. The Emacs/JDEE combination adds features typically missing from command-line tools, including:
    • syntax coloring
    • auto indentation
    • compile error to source links
    • source-level debugging
    • source code browsing

    The JDEE supports both Emacs (Unix and Windows versions) and XEmacs. It is freely available under the GNU public license.

    Note that much of the functionality of JDEE is simply JDEE using other packages like cc-mode, font-lock-mode, etc. It does pull all of these packages together very well.

  • Tags. (from XEmacs info documentation node (XEmacs)Tags:) A "tags table" is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named sub-units) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the `M-.' command which finds the definition of a function by looking up which of the files it is in.

    Briefly, using tags with Java means that your Emacs knows the location and completion of all interesting features (classes, interfaces, fields, methods, etc.) of your project so that you can (a) jump right to the feature definitions, (b) use completion (see the next bullet), (c) do regular expression searches and/or replaces on tags (e.g. global replace of a variable), and more. See the documentation on tags in Emacs info for more information on the use of tags.

  • Completion. When using tags or OOBR, completion can be enabled. When enabled, completion will let Emacs complete partially typed names of interesting features like classes, interfaces, methods, etc. No longer do you have to type those 30 character interface names! Emacs does it for you! Do an Emacs apropos search on "completion" (control-h 'a') for more information. Completion is normally mapped to meta-tab in most modes. (Completion can work even in text mode - it can complete from your local dictionary!)
  • font-lock-mode. When Font Lock mode is enabled, text is fontified (i.e. put into new fonts, colors, styles, etc. depending upon what you are typing to make the display of information more clear) as you type it. While font locking can make for a more pretty/clear display, it can seriously slow down typing/development for large files and long-lived Emacs sessions. Possible solutions include refining font locking (see turn-on-fast-lock and related functions), Lazy Font Locking (see lazy-shot-mode), caching font lock information (see fast-lock-cache-directories), and more.
  • Jacob - The Java Commando Base. Jacob is a Java class browser and project manager for Emacs and includes a powerful class wizard. Jacob is a Java program and its functionality overlaps with that of JDEE, OOBR, and XEmacs. We find it most useful to use all of these tools in tandem, adjusting to fit personal taste.

Our code standard is partially enforced with this elisp code that provides some customizations to CC-mode and more.

JML

The Java Modeling Language (JML) is a behavioral interface specification language and complementary tool that can be used to specify the behavior of Java modules. It combines the approaches of Eiffel and Larch, with some elements of the refinement calculus. We are using JML heavily in the development of all of our Java software. In particular, we use the JML compiler, the JML runtime assertion checker, JMLdoc (the JML version of Javadoc), JMLunit (to generate unit tests from annotations), and more.

Jass

Jass is a pre-compiler for Java the provides support for Eiffel-like code annotations for program specification, trace assertions, and more. We have used Jass heavily in our IDebug framework, but now we use the JML tools exclusively.

ESC/Java

The Compaq Extended Static Checker for Java (ESC/Java), developed at the Compaq Systems Research Center (SRC), is a programming tool for finding errors in Java programs. ESC/Java detects, at compile time, common programming errors that ordinarily are not detected until run time, and sometimes not even then; for example, null dereference errors, array bounds errors, type cast errors, and race conditions.

We are co-developers of the new version of ESC/Java2. See our ESC/Java2 web pages for more information.

IDebug: An Advanced Debugging Framework for Java

IDebug, the KindSoftware debugging framework, is an advanced debugging framework for Java. This framework provides the standard core debugging and specification constructs such as assertions, debug levels and categories, stack traces, and specialized exceptions. Debugging functionality can be fine-tuned to a per-thread and/or a per-class basis, debugging contexts can be stored to and recovered from persistent storage, and several aspects of the debugging run-time are configurable at the meta-level. Additionally, the framework is designed for extensibility. Planned improvements include support for debugging distributed object systems via currying call stacks across virtual machine contexts and debug information logging with a variety of networking media including unicast, multicast, RMI, distributed events, and JavaSpaces. Finally, we are adding support for debugging mobile agent systems by providing mobile debug logs.