Peter Williams

XML Attributes

XML attributes have always bugged me. When I first learned XML I immediately disliked attributes but I was not able to articulate why I did not like them, it was just a feeling. I think I have finally figured out what exactly I dislike about attributes.

I was searching for some best practices in XML design, in an attempt to convince some people I work with that attributes are evil, and I came across Refactoring XML: The Attribute Question. It, rightly, points out that XML attributes are just syntactic sugar. Anything you can express with an attribute you can also express with an element, but not vise-versa, so strictly speaking you do not need attributes. In general, I am all for syntactic sugar, at least the sort that just removes finger-typing by making common choices for you. XML attributes, however, have different semantics than elements, for which they are syntactic sugar. The difference in semantics is a bad smell and has led to endless debates about when and why attributes should and should not be used.

XML would be a lot nicer if attributes were just a short cut for writing an element with simple content. In my perfect world

<person name="Fred"/>

would be exactly equivalent to

<person>
  <name>Fred</name>
</person>

Unfortunately, we are stuck with XML as it stands today, for a while anyway.

Javadocs in the Jar

I recently upgraded to Eclipse 3.1RC1. While importing my project I noticed that you can associate a set of javadocs stored in an archive to a jar your project requires. After noticing this I checked IntelliJ IDEA and found that it can also use javadocs in an archive. I have never used NetBeans but suspect it has the same behavior.

This means that the javadocs for a particular API can be stored in the jar with the API itself. I wonder why this is not common? If it were common IDEs would probably automatically find and use the javadocs in a jar, if there were any, rather than forcing the user to manually associate them. (It is possible that IDEs do this already.) Even better would be standard manifest attribute that specifies the URI of the javadocs, which could be relative to the root of the jar or an external URI. This would allow javadocs to be included in the jar when appropriate and kept external otherwise (though I have a hard time imagining a situation in which external javadocs would really be a better choice) but either way IDEs would still be able to find the API documentation without manual intervention.

From now on any library jars I create will include the javadocs. Even if IDEs cannot find it automatically having the API documentation in the jar is still a better choice than the documentation being completely disconnected from the implementation.

Why Java is Not My Favorite Language — Reason #36

Member access modifiers apply that the class level not the object level. For example, the following perfectly legal in Java.

class Foo
{
    private String name;

    public String someOneElsesName(Foo another)
    {
        return another.name;
    }
}

The method someOneElsesName() returns the value of a private instance variable of an object that is not one on which the method was executed. This is suppose to promote good encapsulation?

It’s a Girl

My wife and I found out the gender of our new baby on Saturday. It is a girl! We were suppose to find out at a scheduled prenatal visit on Monday but the baby was uncooperative. My wife is a planner so not knowing what the gender was not really an option (and I was curious, too). So, we went to one of those commercial ultrasound places and they were able to identify the gender with no problem.

Commenting Code

Mike Clark wrote and article on commenting code and Cedric adds a few things in The Art of Commenting, both are worth reading. I have a couple of other techniques which I find useful.

Make comments complete sentences. It takes a little longer but it helps make the context you have in your head, that the next guy will not, more explicit.

Put comments after the code to which they relate. Keeping it DRY is hard because before you write the code you are thinking about how you will achieve the result you want. How you achieve something it not, generally, useful in a comment. If I want to see how something is done I will read the code. I want comments about what the code achieves, and why achieving that is important. It is easier to comment about what has been achieved, and why, by writing the comments after the code because how you achieved it is already written. In my experience, this practice also leads to comments reading a bit like assertions, which I quite like because it make bugs stand out a bit more.