Sunday, October 26, 2008

Busy busy

Not much written in a while, but that is mostly because I've been busy with different projects. I added a list to this blog with the tiny open source projects I'm working/have been working on.

Naga is my wrapper library around Java NIO that implements the surprisingly complex amount of boiler-plate code you usually need to use NIO for socket client-server communication.

Xmlwise is even more modest. Basically it is a few Java classes that extract data from an already parsed XML document, making the data easy to access by moving it into standard structures (HashMaps and LinkedLists). These classes have made it a delight for me to work with XML documents, and hopefully they'll be of use to others as well.

There are some other libs in progress as well.

Friday, October 10, 2008

The sad sad state of automatic docs

At work I do server programming in Java and after a while I guess you start to get erronous idea that all automatic docs are like javadoc or better.

Oh, so rdoc (Ruby) sucks like the end of the world, and ri is a joke, but those are just exceptions - right?

...or so I thought until I tried to look at some Doxygen documentation for LLVM... It made me want to claw my eyes out to make the horrible thing go away. 

I mean WHAT IS WRONG WITH THE WORLD people!? Look, when old-timers man and javadoc still is the cutting edge, you know you're in a really sad place.

I thought the Objective-C documentation was pretty bad, but it's like a shining beacon of light in comparison.

The bat-crazy thing is that people write stuff like "I love Doxygen, it is teh bestest", like there is even a remote possibly it could be true.

I read one exchange where people argued that the reason Doxygen docs sucked - everywhere - was because people didn't configure it right and didn't stick with the conventions...

I hate to break it to you people but it is a f*****g tool, and a tool is supposed to help, not make you spend hours in configuration and figuring out best practices. So if your so-called tool isn't helpful, you're way better off writing the docs by hand - and I don't care if the tool creates some fancy but utterly unusable class diagrams, it is still worthless.

Javadoc and man already shows exactly what any documentation at least have to live up to. 


It is really easy, here is a check-list on what an auto-doc tool needs.

1. Great formatting. 

Not "acceptable", not "good". It has to be great. You already had to break your coding flow to look something up, so the formatting needs to be crisp sharp to guide you to exactly the information you need as fast as possible so you can get back as fast as possible.

2. Zero configuration. 

Configurable tools suck, yes they suck. Because most of the time "configurability" is nothing more than an excuse for the tool coder not to figure out good defaults for you.

Yes it is worthwhile to have some configurable parameters, but it should be the exception rather than the rule. If things are configurable, then doc A and doc B will look different, and a programmer used to look at docs generated with style A will be confused by style B and vice-versa. In documentation, consistency is king.

Obviously this has to be language specific, but within a language the docs should look the same. If you are making a tool and plan to make the user to configure everything, then you are a lazy bastard.

3. Well thought out and clear doc conventions

Your tool should make it easy for a programmer to know what the can make the auto-doc tool improve the documentation.
Start looking at Javadoc - it is not great but it works. We have the basic @param, @throws and @return. It should be easy to expand that and adapt specific conventions for each language.

4. Remember the needs of the programmer.

Find the common use cases and optimize for them.

When programming Java, in the majority of cases I look up docs for one of three reasons:

  1. To find the correct method to call on a class.
  2. To understand the workings of a method of a class.
  3. To find the correct class to use in a library/framework.

Javadoc is fairly optimized to for this: It's easy to scroll through the methods. If you click a method then the description gives you the basic arguments, and there is a doc convention to describe the most important information (parameters, return value, when exceptions are thrown). 
It is also easy to find a class due to the package structuring and the quick links to implementing classes/subclasses.



Automatic documentation is a solved problem. Too bad no-one seems to be looking at the solutions.

I'm going to finish with a quote from the Qt-list: 
"It's [blaming Doxygen for the bad documentation], or blame almost every single user of the tool. At this point, I'd prefer to blame the tool."
 

Saturday, October 4, 2008

The old static vs dynamic typing...

Instead of rehashing the old arguments, I'd like to point out some observations I've made.

The best GUI builder I've encountered is Interface Builder on Mac OS X and it works because Objective-C is a dynamically typed language. It is very to use and yet incredibly powerful.

What you notice from the beginning, is that you are building the GUI by instantiating flexible objects, instead of creating thousands of subclasses like Java would make you do.

IB is one of the few development tools that actually manage to deliver on the concept of object oriented programming as assembly of reusable building blocks.

What makes this possible is the way dynamic typing naturally decouples the system. It is almost like magic.


Another kind of magic made possible by dynamic typing is dynamic message forwarding.

Here is an example, code is in an imagined dynamically typed Java.

Here is a tree class:

Class Tree
{
  Map m_values;
  public Tree()
  {
  m_values = new HashMap();
  }
  public Object methodMissing(Method method, 
                              Object... args)
  {
  if (args.length == 0)
  {
  return m_values.get(method.getName());
  }
  if (args.length == 1 
        && isSetterMethod(method.getName()))
  {
  set(getVariableToSet(method.getName()), args[0]);
  }
  }
  public Object set(String value, Object object)
  {
  m_values.put(value, object);
  }
  public Object addBranch(String name)
  {
  m_values.put(name, new Tree());
  }

  // return true if the string is a typical 
  // setter, e.g. "setSomeVariable"
  public boolean isSetterMethod(String) { ... } 

  // return variable name from a setter, e.g. 
  // "setSomeVariable" returns "someVariable"
  public boolean getVariableToSet(String) { ... } 
}

We can use it this way:

Tree registry = new Tree();
t.addBranch("settings");
t.settings().setTimeout(100L);
t.settings().setHost("www.google.com");
System.out.println(t.settings().timeout()); 
// prints "100"
System.out.println(t.settings().host()); 
// prints "www.google.com"


Although this kind of coding can be misused, it is immensely powerful when it comes to avoiding boilerplate coding. In fact, the whole concept of automatic code generation used by many Java frameworks becomes completely unnecessary in dynamically typed languages. 

Without dynamic typing, we deny ourselves a range of tools that does not fit in a statically typed universe. If all you've used is statically typed languages it is hard to understand the kind of freedom dynamic typing really give you, and therefore it's also hard to understand what you are sacrificing.

That said, a statically typed language has the advantage of clarity of intent which can be a substantial win in certain situations.

This is why I think that the next big development language ought to be dynamically typed but with optional static typing: the best of both worlds.