[OSM-dev] Josm-patches and osm-lib was:OSM Date Formats

Dave Stubbs osm.list at randomjunk.co.uk
Wed Oct 3 18:58:07 BST 2007

On 03/10/2007, Marcus Wolschon <Marcus at wolschon.biz> wrote:
> > and to (b)
> > document your API properly (and most of all think about which methods
> > make up you API and which should rather be "undocumented" meaning that
> > folks can use them but not rely on them being there forever).
> You mean you don't want to document a program you are writing?
> I thought the aparent lack of javadocs was just lack of time and
> bad style and not even remotely on purpose.
> > If you set the expectation that plugins will continue to work even if
> > you make major updates,
> Do you make that promise now?
> I don't see where a major change would break less
> plugins now then if you let us make it follow proper style.

It's certainly an interesting philosophy... if I do away with the
interface boundary, no-one will know where it is, so I don't have to
worry about it breaking, or having to tell people something changed.
It certainly makes the app easy to hack on, but I probably wouldn't
want to be a plugin developer ;-)

> > I think one of the reasons JOSM is like it is is that there wasn't
> > a lot of manpower available for development, and it would have been
> > too much "bureaucracy" work for Imi (deciding what to offer to plugins
> > and what to shield from them, taking responsibility/guaranteeing that
> > stuff will continue to work, documenting the API etc).

That makes a lot of sense. There's virtually never a good coding
reason not to use good coding style, but there's often a
million-and-one reasons not to bother.

> You are the only one talking about a stable and documented plugin-api.
> Everyone else seems to talk about an offer to implement proper
> coding-style on existing classes. This adding of getters, setters,
> final arguments, javadoc, parameter checking in non-performance-critical
> parts would cost you no work at all because the offer was to implement
> that for you.
> Proper style helps other developers understand, use and debug your code.
> Thus it helps to get more eyes into the project and ease the writing
> of patches and plugins.
> If I found a bug the choice of filing a bug-report versus submitting a
> patch for it is made on the easy of writing that patch for code I am
> not working with on a daily basis.

I just gave the code a quick look over in the SVN. One thing you
absolutely /can't/ accuse it of is being hard to understand. It looks
very well thought out. It certainly isn't a traditional Java way of
doing things as it looks more like a scripting language in places...
but it doesn't look like it'd be hard to write against at all.
Actually, an absolute pleasure given some of the applications I've
seen coded with "standards" that feel like drowning in spaghetti.

It does look like an absolute pig to test though. I'm guessing the
fact that just about everyone uses josm-latest relieve the problem
with that as errors will get picked up early.

> You seem to make a lot of assumptions about providing a stable contract
> to implement where you would actually be left with a documentation
> stating what return-values may be null and what parameters are
> acceptable and thus what third party code is NOT to rely on.
> Currently one takes the code and relies on it to be working the
> same way for the next few versions when writing a plugin because there
> is nothing where you can see "this may be null", "these may be called
> in any order", "this is not guaranteed to be already updated when that
> gets called".

Yes, and if you added all that then they would have to continue to honour it.

> As you don't seem to want it. Okay.
> I'll not offer to do this work for
> you again.

Nice to see people getting worked up about good coding standards. But
maybe you should spend a second to look at it from the other point of
view: anything you do will have to be maintained, you're proposing a
major shake-up of the current code base, and all for very little
obvious benefit in the immediate future. While you're doing all that
plugin writers will be broken completely, and any work other people
are currently doing on the core will be made difficult.

More information about the dev mailing list