Jeez, its so much easier to make recommendations for rules, than to try and follow them to produce meaningful attribute names. It seems there must be some general rule that we're missing concerning when to use nouns vs. verbs for attribute names. Let me continue looking through the API for precedents that determine general rules.
On Fri, Mar 12, 2010 at 10:53 AM, P T Withington <[email protected]> wrote: > I think there is also a precedent for attributes that represent state to be > the past participle, such as `enabled`, `loaded`, `inited`, and `applied`. > Because such attributes also have an implicit event associated, you end up > with an event `onenabled` (which is sent whenever `enabled` changes value), > and similar for the others. I think this is why we have the mish-mash of > events in animator. `onstart` and `onstop` are "pure events", `onpaused` is > an implicit event associated with the `paused` attribute. So there's a > conflict between wanting attribute names to be nouns (so you can't call the > attribute `pause`) and not wanting the event to be in the past tense (so you > can't have the event be named `onapaused`). > > Our documentation convention is only to document "pure" events (and not to > document the event that is implicit with every attribute), so the > documentation (as I plan to fix it) for <animatorgroup> will on document > `onstart`, `onrepeat` and `onstop`. `onrepeat` is messy because it collides > with the implicit event that should be associated with the `repeat` > attribute. Per your guideline that attributes should be nouns, we should > probably rename that to `repetitions` to clear up that conflict. > Instead of using a "repeat" attribute name, how about using "iterations" or "cycles". They are nouns, are more descriptive and remove the overloading of the "repeat" name. I think that "oncycle" is more descriptive than "onrepeat" as a cycle or iteration implies going over the same medium again, while repeat is a more general term: he repeated his steps in a different direction. I understand that we're slicing some mighty fine hairs here, but when you look at everything as a totality, it produces a more intuitive API. > > As to renaming `start` to `autostart` or `autorun`, that's not completely > accurate, because this is an attribute that can be turned on or off > programatically, and it has the effect of stopping (for false) or > re-starting (if true) the animator. It is different from `paused`, because > it starts the animator over from its initial state. I'm leaning toward > using the word `enabled` for this attribute. What do you think? > I'm definitely against "enabled", since this implies that if its not "enabled", then it doesn't have any state -- its no longer a Boolean, so its state can't change. So if its playing and "enabled" is set to false, then you shouldn't be able to stop it from playing. Clearly this isn't the functionality that you're implying. I still favor "autostart" or "autorun", even with its failure to encompass the programmatic considerations that you've pointed out, as these limitations are only a characteristic of the "autostart" or "autorun" implementation. An "autostart" implies that playback will always start from the beginning. Norman Klein > >
