Differences between revisions 2 and 3
Revision 2 as of 2008-11-16 18:33:22
Size: 2634
Editor: ivanGS
Comment:
Revision 3 as of 2009-09-20 21:47:35
Size: 2634
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Lucene's API in inconsistent.

It would be great, if some people could unite to solve this problem.

Proposed steps to achieve API consistency:

  • 1) Identify categories of inconsistencies and define solutions
  • 2) Identify concrete inconsistencies including their occurrences
  • 3) Examine, which components would be affected by possible refactoring
  • 4) Propose patches for refactoring



Let's go


1) Identify categories of inconsistencies and define solutions

Containers don't use Iterable<...> (or more concrete interfaces)

Example:

Why is it bad?

  • Usage of containers must be intuitive and consistent.

Solution:

  • Make use of Java's collection interfaces such as: Iterable<...>, Collection<...>

Public accessible fields

Example:

  • ScoreDoc: "public float score" and "public int doc"

Why is it bad?

  • People shouldn't have to memorize, which functionality is exposed by public fields, and which by public methods.

Solution:

  • No public fields. Look at every serious API. There are no public fields!

Some methods which return values are named something() others are named getSomething()

Example:

  • Fieldable: without get: Reader readerValue(), byte[] binaryValue(), String stringValue(), ... with get: byte[] getBinaryValue(), int getBinaryLength(), ...

Why is it bad?

  • People shouldn't have to memorize, which method starts with 'get' or 'set', which without 'get' or 'set'.

Solution:

  • Methods which somehow represent a property should use names such as getSomething / setSomething Boolean methods could use start with isSomething / setSomething

Some methods don't follow standard Java naming guidelines

Example:

  • QueryParser:

    ReInit(...), Term(...), TopLevel(...) - look to me like constructors!!! enable_tracing(), disable_tracing() - oh my!!!

Why is it bad?

  • People shouldn't have to memorize, which method starts with capital letter, and which doesn't.

Solution:


2) Identify concrete inconsistencies including their occurrences

TODO


3) Examine, which components would be affected by possible refactoring

TODO


4) Propose patches for refactoring

TODO



former bug report, which led to creation of this wiki page: https://issues.apache.org/jira/browse/LUCENE-1439

MakingApiConsistent (last edited 2009-09-20 21:47:35 by localhost)