Thursday February 10, 2005

Finally Centering Blocks

I'm in Prague this week, and having a great time. We're discussing architecture and the java model. It's really exciting, but too early to blog about...

I did find out about some cool new features in NetBeans 4.1 though. For example, if you hold the control key (or on my mac, the Command key) all method calls under the mouse turn into hyperlinks which when clicked jump to the referenced source.

Now for the nerdy technical digression of the week.... I've been doing some debugging at night. After somebody brought up the issue of the <center>> tag (which I've mentioned before), I decided to look into it again. A little debugging led me to the problem in the rendering code. Basically, let's say you're trying to center a table like this:

    <table style="margin-left: auto; margin-right: auto">
      <tr><td>Hello World</td></tr>
    </table>

I'm using horizontal margins as auto to cause centering, which is the CSS way to center - the <center> tag has been deprecated a long time.

In the above html, we have an element with "width", "margin-left" and "margin-right" all set to "auto". According to the width computation rules for CSS 2.1, section 10.3.3,

If 'width' is set to 'auto', any other 'auto' values become '0' and 'width' follows from the resulting equality.

If both 'margin-left' and 'margin-right' are 'auto', their used values are equal. This horizontally centers the element with respect to the edges of the containing block.

My code was doing these rules in the order listed. In the above scenario, yes, width is auto, so the other auto values (margin-left and margin-right) become 0, and then it solves the equation

margin-left' + 'border-left-width' + 'padding-left' + 'width' + 'padding-right' + 'border-right-width' + 'margin-right' = width of containing block

This however means that the computed position is not centered. So instead I'm now first computing the preferred minimum width of the component (using the shrink-to-fit approach used for absolutely positioned elements), and then I split the remaining space in the containing block evenly between the two margins. This seems to give exactly the behavior needed.

After hooking this behavior up to the <center> tag, using page import on the Google home page shows that the google text field area is now correctly centered!

(2005-02-10 07:22:40.0) Permalink Comments [1]

Inheriting javadoc comments

I just learned something new - which I thought I would share.

I always avoid having javadoc comments on methods which implement an interface method. I add a full comment in the interface, explaining the method, its parameters and its return value. However, in the implementation class, I leave out the javadoc completely. That ensures that javadoc will copy the description from the interface instead, which in turn ensures that the comment is accurate since I only have to maintain it in one place. (Had I copied it in when I first implemented the method, and then later changed the description, the implementation copy would go stale. And yes, I've made that mistake in the past...)

This scheme works fairly well, but there are times when I want to add additional comments to the implementing method. For example, adding additional notes useful to clients calling this specific implementation of the interface. When I've done this, I've only included the specific documentation for this method, and then I refer to the interface method itself for the full method description. This is clearly not a good solution either, because when you view the documentation in an IDE javadoc popup, for example, it doesn't include the basic comment which is often more important than the supplemental information.

Well, it turns out there's a way to get javadoc to include the parent documentation, and you can surround it with your own specific comments! Just use "{@inheritDoc} " inside the documentation somewhere, and it will include the super documentation:

/**
 * {@inheritDoc}
 * <p>
 * For this specific implementation of the interface, you're better off
 * calling the more efficient {@link foo} method, provided you have the
 * additional arguments!
 * </p>
 */

More information on this can be found here.

@inheritDoc is available as of JDK1.4. In JDK 5 there's another cool tag to use as well (thanks to Peter von der Ahé, Mr. Javac, who's sitting next to me here in the Prague office, for pointing this one out to me.) Use the @code tag to include code samples inline in the javadoc. No more needing to escape all < and > characters in the javadoc comment as &lt; and &gt; ! And there was much rejoicing...

(2005-02-10 06:55:59.0) Permalink Comments [1]