Visualising technical debt

April 1st, 2013 · Tomas Malmsten · Agile, Processes 7 comments - Tags: process, technical debt

Technical Debt is something most teams struggle with in one way or other. One of the more common issues I encounter is how to visualise the actual cost of technical debt in a way that the business stakeholders understand. To achieve this I have used a special product backlog type with some additional data.

The debt needs to be tracked in two places. A comment of some kind is needed in the code which will identify and remind the developers that the debt have been logged and is being tracked. I have created a TODO like comment which I’ve called DEBT. The tag holds a link to the backlog item which is tracking the debt. When a developer encounters the comment in the code s/he needs to read the item to understand what and how to deal with the debt.

The second place is the issue tracker for product backlog. The backlog item type needs to keep track of three things:

A description.
A time guestimate for how long it would take, in man days, to fix this debt. I usually refer to this as the debt.
Interest. The interest is calculated in man days spent to circumvent the debt.

When a new technical debt item is created two team members should take part. Two are generally better at both describing something clear and at guestimating how long it will take to pay the debt of. The new debt has to be described in such a way that when someone else encounter the debt in the code s/he understands how this debt is paid of and why it is a debt. Usually the code does a good job of this but not always. A guestimate is required. This defines how big the debt is and is central when evaluating if a debt should be prioritised to be fixed. In my experience guestimates are best made in man days, but if the team is used to doing guestimates in hours that’s OK to as long at the same unit is used when tracking the interest. Once the backlog item have been created a DEBT comment has to be added to the code. The comment should be placed where a developer would typically enter the indebted code. The comment should provide a link to the debt item so anyone can log interest against the debt.

When a team member works with the code and encounters the debt s/he reads the debt item description and logs how much time s/he spends on coding around the debt. In other words how much longer does it take to complete the issue at hand then if the debt would not be present. This amount of time should be added to the interest field in the debt item.

Over time, and if the debt is sever this is usually only a matter of weeks, it will become evident that the team is spending more time paying interest on the loan then what they would spend to pay the debt of. Since both interest and debt is illustrated in the same unit this will become clear to non technical stakeholders just as well.

Further to making technical debt and its costs easy to understand for everyone it will also help to illustrate to the team when a debt should not be paid of. I have many times found my self thinking that a particularly messy part of the code really should be cleaned up and then realising that since it is so rarely touched it is really not worth fixing.

Getting started with git-svn

March 6th, 2013 · Tomas Malmsten · Technology No comments - Tags: git, git svn, svn

I just stated a new assignment and they use Subversion for version control. It was years since I last worked with Subversion and have been exclusively using git since. So I decided that rather then going back to SVN and getting confused and frustrated I will use git-svn.

After two days of struggling to check out the larger, and more important, repositories using git-svn I was starting to doubt the value of this. Sure, The reason it takes so long is that git fetches the complete history but SVN only fetches the last revision. But will this wait really pay of?

I then realised two things. Firstly, running three processes at the same time will choke the hard drive, leaving them hanging whilst waiting for each other. So running one at the time makes all of them complete faster.

Second, it’s a good idea to use the flag –log-window-size. This flag tells git-svn how much history it should get each time it fetches history from the SVN server. If the SVN repository has a long history the default value of 100 is way to low. I increased this to 1000 and this greatly improved the performance. However, reading about the flag, there is a warning. If this number is set to high the SVN server may consume to much memory so don’t go overboard.

Another thing worth knowing is that even if the target folder seems empty if the git svn clone command fails or is stopped there is usually a .git folder in it. This contains the work performed up to the point when the task was interrupted. It is possible to resume using git svn fetch rather then starting from scratch.

Edited to add:
Since the source code has some odd ways to add auto-generated code, I.E. not to Mavens target folder but straight into the source, I tried out the command git svn create-ignore. This was however a mistake, at least for my repository. It added a new .gitignore file in almost every folder in the project, all looking pretty much the same. It was quite a hazel to get rid of them so I’d say it’s easier to manually craft your ignore file then to use the tool.

Restlet’s JAXB extension in OSGi

September 27th, 2012 · Tomas Malmsten · Java No comments - Tags: Java, jaxb, restlet

When using JAXB in an OSGi container it is important to load the JAXB context into the correct class loader. This is actually an issue with any framework that has not been release for OSGi and uses class loaders. I ran into this when trying to use Restlet’s JAXB extension.

The fix is actually pretty easy. When using the JaxbRepresentation it’s important to pass the current class loader to the constructor. I extended JaxbRepresentation to make the client code lighter. You can find the code for this below:

package com.tomasmalmsten.restlet.jaxb;

import org.restlet.ext.jaxb.JaxbRepresentation;
import org.restlet.representation.Representation;

public class OSGiSafeJaxbRepresentation<T> extends JaxbRepresentation<T> {
  public OSGiSafeJaxbRepresentation(
        final Representation xmlRepresentation, final String contextPath) {
    super(xmlRepresentation, contextPath,  null,
        OSGiSafeJaxbRepresentation.class.getClassLoader());
  }
}

package com.tomasmalmsten.restlet.jaxb;

import org.restlet.ext.jaxb.JaxbRepresentation;

import org.restlet.representation.Representation;

public class OSGiSafeJaxbRepresentation<T> extends JaxbRepresentation<T> {

public OSGiSafeJaxbRepresentation(

final Representation xmlRepresentation, final String contextPath) {

super(xmlRepresentation, contextPath, null,

OSGiSafeJaxbRepresentation.class.getClassLoader());

}

Feel free to use the above as you see fit.

Mapping java.util.Map to XML using JAXB

May 7th, 2012 · Tomas Malmsten · Java 4 comments - Tags: Java, jaxb, xml

One of the thing that can be a bit tricky when using JAXB is to map a java.util.Map to XML. In this example we have a provider object. The provider has a name and a map containing properties.

Below is the provider XML document:

<provider>
  <name>Provider Name</name>
  <properties>
    <property>
      <name>address</name>
      <value>194.132.9.45</value>
    </property>
    <property>
      <name>username</name>
      <value>testuser</username>
    </property>
    <property>
      <name>secret</name>
      <value>433395868950ifkjjrif9985848rufj</value>
    </property>
  </properties>
</provider>

<name>Provider Name</name>

<name>address</name>

</property>

<name>username</name>

<value>testuser</username>

</property>

<name>secret</name>

<value>433395868950ifkjjrif9985848rufj</value>

</property>

</properties>

</provider>

And then the Provider class:

package com.tomasmalmsten.example.jaxb;

import java.util.Map;

public class Provider {
  private String name;
  private Map<String, String> properties;

  void setProperties(Map<String, String> properties) {
    this.properties = properties;
  }

  String name() {
    return name;
  }

  Map<String, String> properties() {
    return properties;
  }

  void setName(String name) {
    this.name = name;
  }
}

package com.tomasmalmsten.example.jaxb;

import java.util.Map;

public class Provider {

private String name;

private Map<String, String> properties;

void setProperties(Map<String, String> properties) {

this.properties = properties;

}

String name() {

return name;

}

Map<String, String> properties() {

return properties;

}

void setName(String name) {

this.name = name;

}

JAXB sees the properties object in the XML document as a list of property entries. Therefore we need to transform the list into a map. To do this we need three supporting classes. The first one is the class containing the entry, or property:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;

class Property {
  @XmlElement(name = "name")
  private String name;

  @XmlElement(name = "value")
  private String value;

  Property() {
  }

  Property(String name, String value) {
    this.name = name;
    this.value = value;
  }

  String value() {
    return value;
  }

  String name() {
    return name;
  }
}

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;

class Property {

@XmlElement(name = "name")

private String name;

@XmlElement(name = "value")

private String value;

Property() {

}

Property(String name, String value) {

this.name = name;

this.value = value;

}

String value() {

return value;

}

String name() {

return name;

}

Next we need the class that contains the list of entries, or the properties:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

class Properties {
  @XmlElement(name = "property")
  private List<PropertyEntry> entries = new ArrayList<>();

  List<PropertyEntry> entries() {
    return Collections.unmodifiableList(entries);
  }

  void addEntry(PropertyEntry entry) {
    entries.add(entry);
  }
}

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;

import java.util.ArrayList;

import java.util.Collections;

import java.util.List;

class Properties {

@XmlElement(name = "property")

private List<PropertyEntry> entries = new ArrayList<>();

List<PropertyEntry> entries() {

return Collections.unmodifiableList(entries);

}

void addEntry(PropertyEntry entry) {

entries.add(entry);

}

To transform the list into a map we need an XmlAdapter. An XmlAdapter is a class that instructs JAXB on how to marshal and unmarshal an object that does not conform to the JAXB standard. This could for example be a class without a public no args constructor, or as in our case the provider properties map:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.adapters.XmlAdapter;
import java.util.HashMap;
import java.util.Map;

class PropertyAdapter extends XmlAdapter<Properties, Map<String, String>> {

  @Override
  public Map<String, String> unmarshal(Properties in) throws Exception {
    HashMap<String, String> hashMap = new HashMap<>();
    for (PropertyEntry entry : in.entries()) {
      hashMap.put(entry.name(), entry.value());
    }
    return hashMap;
  }

  @Override
  public Properties marshal(Map<String, String> map) throws Exception {
    Properties props = new Properties();
    for (Map.Entry<String, String> entry : map.entrySet()) {
      props.addEntry(new PropertyEntry(entry.getKey(), entry.getValue()));
    }
    return props;
  }

}

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.adapters.XmlAdapter;

import java.util.HashMap;

import java.util.Map;

class PropertyAdapter extends XmlAdapter<Properties, Map<String, String>> {

@Override

public Map<String, String> unmarshal(Properties in) throws Exception {

HashMap<String, String> hashMap = new HashMap<>();

for (PropertyEntry entry : in.entries()) {

hashMap.put(entry.name(), entry.value());

}

return hashMap;

}

@Override

public Properties marshal(Map<String, String> map) throws Exception {

Properties props = new Properties();

for (Map.Entry<String, String> entry : map.entrySet()) {

props.addEntry(new PropertyEntry(entry.getKey(), entry.getValue()));

}

return props;

}

Now what is left is to tell JAXB to use the XmlAdaptor when handling the properties field. To do this we use the @XmlJavaTypeAdapter annotation. Below is the fully annotated Provider class:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import java.util.Map;

@XmlRootElement(name = "provider")
@XmlAccessorType(XmlAccessType.FIELD)
public class Provider {
  @XmlElement(name = "name")
  private String name;
  @XmlElement(name = "properties")
  @XmlJavaTypeAdapter(PropertyAdapter.class)
  private Map<String, String> properties;

  void setProperties(Map<String, String> properties) {
    this.properties = properties;
  }

  String name() {
    return name;
  }

  Map<String, String> properties() {
    return properties;
  }

  void setName(String name) {
    this.name = name;
  }
}

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlAccessType;

import javax.xml.bind.annotation.XmlAccessorType;

import javax.xml.bind.annotation.XmlElement;

import javax.xml.bind.annotation.XmlRootElement;

import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;

import java.util.Map;

@XmlRootElement(name = "provider")

@XmlAccessorType(XmlAccessType.FIELD)

public class Provider {

@XmlElement(name = "name")

private String name;

@XmlElement(name = "properties")

@XmlJavaTypeAdapter(PropertyAdapter.class)

private Map<String, String> properties;

void setProperties(Map<String, String> properties) {

this.properties = properties;

}

String name() {

return name;

}

Map<String, String> properties() {

return properties;

}

void setName(String name) {

this.name = name;

}

Get Maven to work with Java 7u4 on a Mac

May 2nd, 2012 · Tomas Malmsten · Java No comments - Tags: Java, maven, OS X

I have finally install Java 7 on my laptop. The Java install runs just fine. Getting maven to find it however was a little tricky.

To make Maven find Java 7 the JAVA_HOME variable is required again. This hasn’t been used for a while since Maven have been able to find Java anyway. But with the switch to 7 Maven still uses Java 6 by default.

I always use .bash_profile to change my environment variables since I tend not to need them else were. It is located in the users home directory (I.E. ~/.bash_profile).

The path to the new Java install is ‘/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home/’. So the complete setting should look like this:

$JAVA_HOME=/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home/

When this has been configured Maven will use Java 7.

« Older Entries

Tomas Malmsten . com

Visualising technical debt

Getting started with git-svn

Restlet’s JAXB extension in OSGi

Mapping java.util.Map to XML using JAXB

Get Maven to work with Java 7u4 on a Mac

Subscribe via Email

Brows by category

Blogroll

Visitor locations

Archives

Trackbacks

Site License

Tomas Malmsten . com

Visualising technical debt

Share this:

Getting started with git-svn

Share this:

Restlet’s JAXB extension in OSGi

Share this:

Mapping java.util.Map to XML using JAXB

Share this:

Get Maven to work with Java 7u4 on a Mac

Share this:

Subscribe via Email

Brows by tags

Brows by category

Blogroll

Visitor locations

Archives

Trackbacks

Site License