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:
IndexSearcher: "int maxDoc()" and "doc(int i)"

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:
All such methods and fields MUST be renamed use Java's recomended naming scheme.

http://java.sun.com/docs/codeconv/html/CodeConventions.doc5.html#381

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

  • No labels