Greg - 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?)
I'm not trying to convince you that a suffix *should* be added to these class names, I'm just trying to understand the reasoning why they don't have one right now. Hopefully the length of the email also serves to persuade you that I am not just trying to bug you with inane questions, and I that have put plenty of thought into this myself. However will I understand if you don't have the time or inclination to continue. On 28 July 2011 02:16, Greg Brown <[email protected]> wrote: >> Actually, I'm not sure that logic does follow. Obviously the >> Component suffix is (sanely) not used, but plenty of others are. > > 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. I see a particular benefit here because the Query suffix informs that although it is a Task, it should be primarily looked at as a Query. So I see it as essentially overriding any previous prefix/suffix or other naming 'hints' and setting a kind of conceptual 'high water mark' in the class hierarchy. Name ends with 'Query' == think of it as a org.apache.pivot.web.Query >> TaskGroup implements a Group<Task> and extends Task, but its name >> doesn't reflect that it is a Task, perhaps just because the word >> 'Task' would be included twice. > > Correct - it is redundant. You only need to qualify things if their meaning > is ambiguous. Since 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? Are you defining it that way now, perhaps alluding to the fact that "TaskGroup extends Task" == "task" and "TaskGroup implements Group<Task>" == "that is a group of tasks"? That does make perfect sense but only with the knowledge of the class itself and ... If it is the case that the 'Task' suffix is not required because it can be inferred from the superclass, then I still don't see why that wouldn't also be true of the 'TaskGroup' prefix being inferred from the class' implements clause. Both parts seem equally important to me. The 'TaskGroup' part to know that the Group interface is used to provide & manipulate the Tasks, and the 'Task' suffix to know that it is a Task and can be executed and used as such. (Not catching that is where my original troubles seem to stem from) As mentioned in my previous email, I see ambiguity between ButtonGroup and TaskGroup for example. Given Pivot's API, I wouldn't expect a class named 'TaskGroup' to extend Task any more than I would expect one named 'ButtonGroup' to extend Button (or Task for that matter). Given that, I doubt you mean that the 'Task' suffix is redundant because can be inferred from the 'TaskGroup' name alone. 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. (Consistency within Pivot's API is commendable and one of the things that helped me to pick it up quickly. It also gives a very professional feel to the API. Every time I use a class with a familiar naming convention, I know I have already saved some some time.) If those 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 seems like a missed opportunity to me. The extra characters make an explicit *suggestion* that these classes extend Task. Obviously it cannot be taken as fact, but it is a very good start on the way to preventing confused users. One of the reasons that this thread arose when it did is because these classes were not even on my radar until a few days ago. If they had a 'Task' suffix they might well have have stood out more and I wouldn't have dismissed them simply as special purpose Group and Sequence implementations without looking any further. (Naming conventions work both ways) >> What if TaskGroup had a companion class that also extended Task and >> implemented Group<Runnable>? It might wrap each Runnable in a Task >> and delegate to TaskGroup for execution. (Kind of a parallel Runnable >> -> Task adapter). >> >> Should that be named RunnableGroup or RunnableGroupTask? > > Difficult to answer since the question is somewhat contrived. We tend to > focus heavily on real use cases since that also helps us come up with the > most accurate names for the things that are being modeled. 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... FooTask // Task in some way connected to Foos (no idea if 1 or many) FooGroupTask // Task in some way connected to a Group of Foos RunnableGroupTask // Task in some way connected to a Group of Runnables IOTask // Task that performs some sort of IO Image.LoadTask // Task that loads an image LoadDataTask // Task that loads some unknown type of data RefreshFileListTask // Task that refreshes a List of Files My logic would continue TaskGroupTask // Task in some way connected to a Group of Tasks but Pivot's TaskGroup doesn't fit TaskGroup // Task in some way connected to a Group of Tasks meaning I end up at TaskGroup // Group of Tasks when I read that class name. (Hopefully that is clear, even if it is not how you see things.) As I mentioned above, it just seems a missed opportunity to prevent potential confusion.
