> Thanks for bearing with me. I assure you these are genuine > questions asked because I get the impression you have studied API > design quite a bit, or at the very least have an interest in it, and > some strong opinions. (What other kind are worth a damn?)
:-) >> We have used suffixes where there is no common alternative. For example, we >> have "TabPane" but not "AccordionPane". Similarly, we have >> org.apache.pivot.web.Query, not "QueryTask". > > Yes, and then there are DeleteQuery, GetQuery, PostQuery & PutQuery. That's because these names need to be qualified. You wouldn't know what a "Delete" is, so we need to make it explicit. >> a "task group" is defined as a "task that is a group of tasks", the there is >> no ambiguity and the "Task" suffix is unnecessary. Same for "task sequence". > > Where is "task group" defined like that? In the API. That's what the TaskGroup class represents (though the Javadoc obviously does not make this clear). ;-) > That does make perfect sense but only with the knowledge of > the class itself... Right - some classes are just like that. You can't always bake everything you need to know about a class into the name. > Both parts seem equally important to me. The 'TaskGroup' part to know > that the Group interface is used to provide & manipulate the Tasks, I think that making TaskGroup a Group was a mistake on my part. There is no need to ensure uniqueness here. In retrospect, I think these classes should have been called ParallelTaskGroup and SerialTaskGroup (no association with the Group interface). They should extend an abstract base class called TaskGroup that defines a sequence of tasks (i.e. getTasks():TaskSequence). TaskGroup would itself extend Task. I think that API helps makes it clear what each of these classes does. > and the 'Task' suffix to know that it is a Task and can be executed > and used as such. Not to be rude, but...RTFM? :-) It is pretty clear from the Javadoc that TaskGroup extends Task. > If all of the other examples of classes that extend Task have a suffix > (be it 'Task' or 'Query', with org.apache.pivot.web.Query itself being > a special case) then I see a discrepancy which could lead to thinking > that TaskGroup and TaskSequence are not Tasks until they are more > closely examined. This comes back to my Accordion example. Did you assume that an Accordion was not a component because it was not called AccordionComponent? Probably not. "Accordion" is a natural name for this type of control, so a suffix is not necessary. Also, Accordion lives in the org.apache.pivot.wtk package, which you know primarily contains user interface components. Similarly, TaskGroup and TaskSequence live in org.apache.pivot.util.concurrent along with a handful of other classes, all of which are used to support the Task class. So that's a pretty strong clue as to what these classes do. > If...other classes have a suffix, and are instantly identifiable > as a Task just by class name, then why not these? Or should the > others not have them either? Or is it just personal preference and > readability? It is readability. We don't design class names for machine parsing. We design them for use by people, and the English language does not always map perfectly to things we want to model in code. > It is a genuine question asked in an attempt to understand the naming > of these two classes. My logic (understandably) makes sense to me, > but I just can't see where/why we differ regarding the suffix. > > Here is a quick dump of how my brain works... > > We both seem to agree on the Group naming > Group<Foo> == FooGroup // Group of Foos > Group<Task> == TaskGroup // Group of Tasks > Group<Runnable> == RunnableGroup // Group of Runnables > > So the above question was intended to ask if you would consider the > 'Task' prefix to be redundant on things like this... Again, I think part of the problem is that TaskGroup shouldn't actually *be* a Group. It should *have* a sequence of sub-tasks. I think that would help alleviate some confusion.
