1. Programming Guidelines
    1. Commit Messages
    2. KDE Development
    3. Suggestion for Version Numbers throughout Nepomuk
  2. Java
    1. Logging

TracNav

edit

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.

Suggestions for change, like Maven for Management, Ruby On Rails, Python hacks, are good and can be discussed on the tf-collaboration mailinglist. When we have new findings, this page will be updated.

To learn about programming, go to the

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.

KDE Development

The KDE parts of Nepomuk are developed by Sebastian Trüg at this SVN:

svn://anonsvn.kde.org/home/kde/branches/work/nepomuk-kde

Suggestion for Version Numbers throughout Nepomuk

Version numbers are needed for all plugins, interfaces, WSDL files, etc, so that you know which version you depend on.

Suggestion by Leo to use year and month numbers for releases and version numbers: The problem with bigger projects and many packages is, that each package starts increasing the version number to its own rules, for example when the interface changes very much, and code is incompatible, the major version changes. Then you move from 1.6.234 to version 2.0.1. But the version numbers used are up to the developers, they could also increase the major number every month to signal that their product is "oh so very far that we have version 5.0 already, after one year". As Nepomuk has to release major releases in known dates (firecracker, roman candle, red meteor) in month 12, 24, 36. To have all components be compatible at this date, the version number could be 2006.12, 2007.12, 2008.12, signalling that it is the official "December 2006" release. The advantage is, that all plugins, features, packages use the same version number "2006.12" and don't have to think about what numbering scheme to use.

Suggestion by Enrico: Everybody uses version numbers as wished for your plug-ins / features. People export their plug-ins / features to the EclipseTargetPlatform when they are not broken and provide significant improve / extension. Then, the EclipseTargetPlatform aggregates all other projects in a stable manner. Tagging the EcpliseTargetPlatform? with version 2006.12 would make an release like Firecracker possible without the need to synch all sub-projects version numbers.

The EclipseTargetPlatform provides all version numbers of all included plug-ins / features, and the tag-section of the svn repository may provide all sources of all versions ever exported into the EclipseTargetPlatform.

Java

Guidelines for Java programmers. Independent of IDE, application, etc. simple java recommendations.

Logging

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");
    }

}

Usage of log levels (copied from gnowsis, please review): * Leo thinks this description is ok for nepomuk.

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.