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

[Frederik Ramm]

Hi,

> You mean you don't want to document a program you are writing?

No, that was not what I said. I said that once you start towards a
"proper" API (as opposed to "everything is public anyway, do what you
want"), then you have to document that. And if you're using all your
available resources to implement new features that help people
mapping, then you may not want to allocate resources to define a
working dividing line between "internal" and "external" stuff and
document that. 

> I thought the aparent lack of javadocs was just lack of time and
> bad style and not even remotely on purpose.

Let's not say "lack of time", instead "time spent elsewhere to
everyone's advantage". And let's replace "bad style" by "non
mainstream style", everything else would be quite arrogant.

> 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.

Part of what you're talking about is trivial (the getters and setters
stuff can even be done automatically). But all this amounts to little
more than "pretty printing", just an exercise in code reformatting,
unless the person doing it can actually add *valuable* documentation
and make *sensible* decisions on where to add getters/setters and
where not.

(How often have I seen a method called "setFoo(x)" with a comment
"Sets Foo, @param x the new value for Foo" - a prime example of
someone putting in a comment for the sake of putting in a comment,
with zero substance, just because some coding guidelines say that you
must have a comment.)

> 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.

[...]

> 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 it would be really helpful to get to a state where this
information was readily available for a plugin developer. I cannot see
how the adding of getters and setters where there now is a public
variable would yield that information. I can even see someone changing
every single JOSM source file by adding getters and setters without
actually understanding the tiniest bit about what JOSM is doing!

Bye
Frederik

-- 
Frederik Ramm  ##  eMail frederik at remote.org  ##  N49°00.09' E008°23.33'