Re: [e4-dev] e4, conventions, OSGi, ... - We need to set up rules

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

Hi Tom, some comments below...


Tom Schindl wrote on 09/13/2009 07:24:41 AM:

> 1. Interfaces start with an I

+1

> 2. Model starts with an M

Don't have a strong feeling about this, but sounds
reasonable.

> 3. Declarative Services vs Extension Points

As Tom pointed out it's not so simple. They are quite
different tools and both have their uses. I think the more accurate comparison
is "Declarative Services vs static accessors", which I think
we all know the answer to. Where we find ourselves out of habit tempted
to add API classes with static methods we should instead use services consumed
via injection.

> 4. Import Package vs Require Bundle

I'm not sure if we will (or need to) reach consensus
on this. I think a useful starting rule is to only use Import Package if
the package is versioned. Whether you design an API to be consumed/implemented
at package or bundle granularity may depend on which e4 component you're
working on.

> 5. Compiler Settings, Formatting + JavaDoc
> ------------------------------------------
> * I think we should provide prefernces people can import into their
>   workspace to setup the formats, ...

Even better is to check the project-level settings
into CVS. It's a bit more work to keep them updated, but the most reliable
way to ensure they are followed consistently. People may have a variety
of different projects in their workspace that want to use different conventions
so workspace-level settings don't always help.

> * JavaDoc:
>   * Class Documentation (even internal class)
>   * plublic/protected method documentation (even internal classes)

I'm a big fan of javadoc but would only push for it
for internal classes where it's providing meaningful information that isn't
conveyed already by the class/method names. It's a point worth thinking
about though. Growing the community and contributor base is an important
goal, and meaningful documentation inside the code is a big help towards
that. 

John