[Lucene-java Wiki] Update of "MakingApiConsistent" by ivanGS

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucene-java Wiki" for change notification.

The following page has been changed by ivanGS:
http://wiki.apache.org/jakarta-lucene/MakingApiConsistent

The comment on the change is:
Please unite to improve Lucene's API consisteny !!!

New page:
= 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 patch 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

----
=== 2) Identify concrete inconsistencies including their occurrences ===

TODO

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

TODO

----
=== 4) Propose patch for refactoring ===

TODO

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