On 28 July 2011 06:06, Greg Brown <gk_br...@verizon.net> wrote: >>> 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.
Yeah, I agree they wouldn't mean much on their own, but that brings me back to the 'TaskGroup == <Group>Task' thing. Without a suffix, some meaning is also lost. Without the 'Task' I don't know what a TaskGroup is, just the data type & structure that it probably represents. Adding the Task suffix won't tell me everything, but it would help. My main point here was more the value that the qualifying suffix can give, regardless of whether it is strictly required. This kind of thing can certainly be taken to extremes though. For instance some organizations have arcane database naming rules that prefix a kind of Hungarian Notation into the names of everything. It gets worse when they also choose to abbreviate by removing vowels and the like. In the end the only people who can decipher them at a glance are the DBAs with tools that make the naming redundant. >>> 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 makes me feel a little less stupid. It is a bit of a stretch to get to 'is defined as' from 'what it represents', and expect users to fill in the gaps. If I know of a class and its intent, then the name could be seen as having little consequence other than aesthetics. My original questions were about the intent of the classes, so that side of things could certainly be improved to help the slower users like myself. >> 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. Yes, unless you are fond of 2 page wide class names, a class is unlikely to capture every bit of pertinent information, but with these classes, it seems like more of an over eager pruning of information has occurred just to make the class names sound a little more natural. They could easily have the Task suffix 'baked in' to indicate that they are Tasks, but they don't because it was deemed redundant (or just ugly). I don't see Task bit as redundant, but do see its 'loss' as a missed opportunity. If there is a problem with the readability of a class name such 'TaskGroupTask' for instance, it suggests that the name is not right and perhaps there is a better way to express it (maybe by looking at it from the another angle such as how it will be used as opposed to what it is). Discarding part of it so that it reads better seems like a hack for want of a better word and only addresses part of the problem. (Your suggestion in an upcoming paragraph is much better IMO) >> 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. Yes that would certainly be clearer in my eyes. The reuse of 'Group' is unfortunate but understandable. The name ParallelTaskGroup would certainly raise a few questions in my mind and drive me to investigate further, unlike the 'camouflaged' TaskGroup. >> 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. Yes, it is perfectly clear, but only once you get that far. The point there is obviously that if the suffix existed in the name, then it might direct someone to the javadocs in the first place. It is not as if it is supposed to be a hidden implementation detail after all. It is how you make it do the one thing it does. If TaskGroup was named ParallelTaskGroup, ParallelTaskExecutor or something similarly far removed from its current name, I wouldn't be stressing the 'Task' suffix. I'm mainly doing it now because without it, it just sounds like a Group<Tasks>, and it is used in the other named Task subclasses. 'TaskGroupTask' is undoubtedly clunkly, but at least is suggestive of the class being more than a Group<Task> - specifically that it is a Task itself. 'TaskGroup' is nicer, but gives no indication that this is anything more than a Group<Task> which it clearly is. 'Group' or 'Task' on their own are even simpler and nicer still, but lose yet another layer of information. I'll take clunky but accurate, over pretty but vague or misleading any day, though I don't think it has to be that black and white in most cases >> 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. I am fine with Accordion and other equivalent Component names. As you rightly say, the name is a natural description, used elsewhere, and the Component part would generally be considered gratuitous. Components do have much more thorough documentation and examples though, which would lessen the chance of mistaking one class for another. Even if ListView were simply called List, the documentation and examples would be there to assist. (It might be argued that Skin classes don't need the 'Skin' suffix either, but that is another matter entirely.) However I *did* initially miss that TaskGroup was a Task precisely because of the class name, and the fact that its conjured up a mental image of a simple Group<Task>. Even after spending a few hours trying to figure out its intent, I was still not focusing on the fact that it was primarily a Task. As our previous emails discovered, doing so would have changed my perception of the class substantially and help me understand that it was indeed working as intended. That might well be because it was late and I should have given up in order to continue with fresh eyes in the morning. But that does happen from time to time. > 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. The small size of the package is a strong point, but while these 2 classes do live in the concurrent package, there are plenty of examples of FooSequence (but not so much FooGroup) outside of the collections package, so they don't look out of place. As you said, the use of Group/Sequence in the name is perhaps a contributing factor here. An unforunate red herring. >> 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. OK, that gets more to the crux of it. I agree TaskGroup is more natural than TaskGroupTask, but at the expense of some lost metadata from the name. I think discovery of classes within an API is worth considering too and often overlooked. A beautifully named class that I never find (or overlook) won't being me much joy. I may curse a class with a clunky name, but will quickly forgive everything if it does what I expect it to. >> 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. > Yes it would help in part, but its alternate name might also lack clarity and benefit from the Task suffix if it extends Task :) Anyway, I think that has finally cleared this up for me. Thanks for your patience.
