1. Programming Guidelines
    1. Sourcecode Documentation
    2. Unit Testing
    3. Commit Messages
    4. Creating Tickets
    5. Java Logging
      1. What log levels do we use and what do they mean?
      2. The time-saving logging shortcut

TracNav

Programming Guidelines

NEPOMUK Java developers should follow these guidelines. If you don't, don't be surprised if your code gets removed from SVN.

  • EclipseDevelopment - tips and tricks using Eclipse to write OSGI components and other stuff
  • JavaNamingConventions - how to name projects, plugins, features, packages
  • VersionManagement - how to make a release, how to version your code, what to care for when packaging OSGI or KDE code.

To learn about programming, go to the

KDE? Are you in the wrong wiki? The KDE parts of Nepomuk are developed by Sebastian Trüg at here:  svn://anonsvn.kde.org/home/kde/branches/work/nepomuk-kde

Sourcecode Documentation

All code must be documented. Each class and interface must have at least one sentence explaining what it does, major methods must be documented. Each file must have an @author tag, otherwise it is impossible to assing code authorship/copyright to legal bodies and we run into legal problems. Code that is not documented may be deleted without further notice, if you even forgot to put your author-tag into it, you may not get informed about it..

Unit Testing

All backend code should be tested using JUnit tests. We have a complete NepomukMockup environment, making it really easy for you to write JUnit tests.

Frontend code must be well documented and the intended behavior of the frontend should be documented also on the UsingNepomuk pages.

If you change a GUI, please update the UsingNepomuk pages and check if you broke something by seeing if the stuff described there still works. If an end-user documentation page is helplessly outdated, fix it a bit.

  • NepomukMockup - read on to learn about painless testing and developing.

Commit Messages

Excerpt from the FreeBSD guidelines:

Good commit messages are important. They tell others why you did the changes you did, not just right here and now, but months or years from now when someone wonders why some seemingly illogical or inefficient piece of code snuck into your source file. It is also an invaluable aid to deciding which changes to MFC and which not to MFC.

  • Commit messages should be clear, concise and provide a reasonable summary to give an indication of what was changed and why.
  • Commit messages should provide enough information to enable a third party to decide if the change is relevant to them and if they need to read the change itself.
  • Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up.
  • Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. In the case of documentation files, it can make the job of the translation teams more complicated, as it becomes difficult for them to determine exactly what content changes need to be translated.
  • Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages.
  • Relate to the tickets fixed using ticket:1 or #1 notation. TRAC will create links to the tickets.

Commit messages like the following aren't very helpful:

  • "not needed" -> uhm, what is not needed?
  • "bye bye" -> was some obsolete code removed? Or did somebody leave the project? Or what?
  • "Reverse to match values" -> Reverse which values to match what?
  • "Move to supported games" -> move what?
  • "Forgot *.xpm files" -> forgot what about them?
  • "One more file to fix"
  • "This difference only applies to Ruby" -> which difference?
  • "" -> empty commit messages are about the worst you can do :-/ (short of insults and totally offtopic messages).

Always keep in mind -- those message are often read *without* seeing the diffs, and without the possibility to see which other files you commited just before that particular commit!

Compare this to

  • "Change CVS keywords to SVN keywords"
  • "Deleted apache xalan dependencies, not needed in Java 1.5"
  • "Added compression tool for kyra speech files."
  • "Add patch 1374870 - fixing wiki parser error described in ticket:1"
  • "Fixed ticket:2 by rewriting RDF validator using rules"

Don't be too verbose in your message either. You don't have to tell people what the next step in the grand scheme are in a long paragraph.

Creating Tickets

Best practice when creating tickets is to enter e-mail addresses of all persons possibly involved with the issue in the ticket's CC field. The respective people will get e-mail notifications upon ticket changes. Discussions can take place as a sequence of ticket comments this way.

Java Logging

Use java.util.Logger.

Read on how to generate log messages, how to read and configure the framework, see LoggingFramework.

In an e-mail discussion on implementation, we came to the conclusion that there are many good logging frameworks, but we can forward all their messages to OSGI logging. Therefore, to use the simplest logging framework to generate these messages, we decided to use standard Java Logging for generating log messages.  Discussion e-mail thread.

To generate log messsages: 

package test;

import java.util.logging.Level;
import java.util.logging.Logger;

public class Hello {
    
    private static Logger log = Logger.getLogger(Hello.class.getName());   

    public static void main(String[] args) {
        log.fine("started");
        try {
            int i = 7/0;
        } catch (Exception x)
        {
            // this will include the type and message of the exception into
            // the log message and is handy. You must pass X as object,
            // to get the stacktrace into logging!
            log.log(Level.WARNING, "Cannot divide by zero: "+x, x);
        }
        log.info("Dear user: division by zero successfull");
    }

}

What log levels do we use and what do they mean?

  • SEVERE - a severe error has occured, that has implications for the user. For example, some data could not be saved or half of the system just crashed.
  • WARNING - WARNING is a message level indicating a potential problem. In general WARNING messages should describe events that will be of interest to end users or system managers, or which indicate potential problems.
  • INFO - a message that is definitely interesting to the user. You must not place debugging messages here. Info messages can say that an important message is here, that the user should read now. If the user wonders what the gnowsis is doing at the moment, an info message may be good.
  • CONFIG - shows that the configuration of the system is ok or is wrong. These messages should reflect only things that can be changed by changing the configuration. For example, when config files are read and weird values are found, a config message is the right thing. If config files are broken totally, INFO or SEVERE is better.
  • FINE - these message are interesting for all programmers. They are normal debug messages that show basically what the system is doing at a higher level, but don't go into details. They do not harm performance
  • FINER - these message are interesting for a debugger of a certain module. When you think that something is wrong or want to know details, FINER is good.
  • FINEST - these are incredibly intense, like on the level of method calls. They cause serious performance problems and flood the logging. They are ONLY allowed for intense debugging. If you switch to FINEST level, your log file can increase up to 100MB in minutes.

The time-saving logging shortcut

You hate to write these again and again? 

    private static Logger log = Logger.getLogger(Hello.class.getName());

Then:

  • create a new template in Eclipse (Window>Preferences>Java>Editor>Templates>New)
    • Name: [your shortcut] *I use 'log'
    • Context: Java Type Member
    • Pattern: 
      ${:import(java.util.logging.Logger)}
private final static Logger log = Logger.getLogger(${enclosing_type}.class.getName());
${cursor}

Every time you need it: type '[your shortcut] or 'log' ' and CTRL-SPACE. It will happen, just as with sysout and CTRL+SPACE.