Programming Style Guide

From FujabaWiki

Table of contents

1 Abstract 2 Introduction 3 Common 4 Pretty Printing 5 Task Tags 5.1 Eclipse Settings 6 Implementing Associations 7 Glossary 8 References

Abstract

The programming style guide provides information about how to layout Java source code, naming conventions and implementation guidelines for attributes and associations between classes.

Introduction

The style guide in this pre release version has to be read as follows. If you are looking for a certain rule, first look if there is a rule for your problem in this page. If not, look into the cross references style guides. The references are prioritized which means that a rule in a style guide with higher priority (descend order) has to be taken however you feel more comfortable with a rule in another style guide. Currently, this is a living document. This means if you find a rule in a referenced style guide copy it into this document. This allows a faster look up of rules for other persons.

Common

1. Project language is ENGLISH
2. All names, comments, checkin messages USE ENGLISH ONLY.
3. This is a team project. Thus, THE CODE IS NOT YOURS, but is owned by the whole group. The most important maintenance problem for code is readability. THE CODE MUST BE EASY TO READ by yourself and by your team mates. Easy to write is not a goal.
4. Documentation: Each class, attribute, and method must lead a functional, expressive description. In case of using Java use javadoc tags to generate HTML documentation later.

Pretty Printing

The pretty printer (code formatter) ensures a common layout and adds among other things headers, footers and generic JavaDoc comments.

There are different ways to pretty print source code:

1. CVS-Repositories:
   1. Java 1.4 Source Code: The pretty printer is provided by our CVS server. When checking in, sources are automatically pretty printed.
   2. Java 1.5 Source Code: Our pretty does not work for Java 1.5 syntax. See below how to pretty print manually.
2. Subversion-Repositories:
   1. The Subversion server has no support for pretty printing.. See below how to pretty print manually.
3. Manual Pretty Printing:
   1. This is a style for Eclipse: Fujaba Pretty Printing Style (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/FujabaCodeStyle.xml). You can import this style under Window/Preferences/Java/Code Style/Formatter. Pretty print your modified files by ctrl-shift-f in the Java editor within Eclipse.
   2. This is another style for code templates: Fujaba Code Templates (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/FujabaCodeTemplates.xml). You can import this style under Window/Preferences/Java/Code Style/Code Templates. The templates will be used when creating new files, methods, etc.

Task Tags

Developers often reach a point where their current implementation works in some or most cases but either exceptional cases are not covered or the code could use some refactoring to improve maintainability or readability. In order not to forget where something remains to be done they annotate their code with special tags that can be displayed in the Eclipse tasks view.

To define a common standard for these tags in Fujaba we agreed on the following tags (with descending priority):

1. FIXME
2. Fixme
3. fixme
4. TODO
5. Todo
6. todo

Pieces of code that contain known bugs should be annotated with "fixme", "Fixme", or "FIXME" depending on the bug's severity.

So if the remaining work is rather small or just a minor usability tweak the "todo" tag should be used. Bigger improvements that are not related to bugs however should be annotated with "Todo", or "TODO".

Each tag should be accompanied by one or two sentences that exactly describe what has to be done at that point.

Please note that all tags are written as one word so tags like "fix me" or "TO DO" are not allowed!

Eclipse Settings

In order to ease your Eclipse configuration we exported the task tags and tasks view settings into a configuration file (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/TasksViewConfigutation.epf) (see Fujaba4Eclipse online help). After applying these settings your tasks will be configured as follows: Since Eclipse only provides three priorities and no possibility to extend these, all fixme tags (FIXME, Fixme, fixme) have the priority "high", the "TODO" and "Todo" tags have the priority "normal" while the "todo" tag has the priority "low".

Implementing Associations

Different kind of association have to be implemented using the Fujaba association templates.

Glossary

Generally all variables should get speaking names. Abbreviations should be considered "bad".

In frequently used cases one may use common abbreviations, e.g.

• i,j as index variables
• it, iter as shortcut for iterator

Never use:

• enum as abbreviation for enumeration

References

Pretty Printer:
Eclipse configuration file for built-in pretty printer (code formatter) (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/FujabaStyle.xml)
Eclipse configuration file for code templates (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/FujabaCodeTemplates.xml)
Eclipse configuration file for the tasks view (http://www.fujaba.de/fileadmin/Informatik/Fujaba/Resources/Downloads/TasksViewConfigutation.epf)
Software::Pretty Printer (For Java 1.4 based source code only) (http://jrefactory.sourceforge.net/cspretty.html)

External style guides:
Code Conventions for the Java™ Programming Language (http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html)
Java Programming Style Guidelines from Geotechnical Software Services (http://geosoft.no/development/javastyle.html)

Documenting with JavaDoc:
How to Write Doc Comments for the Javadoc™ Tool (http://java.sun.com/j2se/javadoc/writingdoccomments/index.html)