Re: [Bug 17334] (setTargetValueAtTime): AudioParam.setTargetValueAtTime is misleading and underdefined

Den 2012-06-28 20:26:05 skrev Chris Rogers <crogers@google.com>:

> On Thu, Jun 28, 2012 at 9:16 AM, olivier Thereaux <
> olivier.thereaux@bbc.co.uk> wrote:
>
>> hi Ray,
>>
>> On 28 Jun 2012, at 16:48, Ray Bellis wrote:
>>
>> > On 28/06/2012 15:23, olivier Thereaux wrote:
>> >
>> >> However… I may be misunderstanding the essence of this method, but
>> >> aren't we talking about a value to be reached at a certain time (or,
>> >> in other words, a value pre-set for a given time)?
>> >
>> > I think you must made my point for me ;-)
>>
>> Always happy to helps ;)
>>
>>
>> > Chris Rogers described it thus:
>> >
>> > "It's a *target* value which we start approaching at precisely the  
>> time
>> > given."
>> >
>> > which I read to mean that the time given is the _start_ of the curve,
>> > not the end of it.
>>
>> I hadn't read it that way, but now that you mention it, yes, it makes  
>> more
>> sense.
>>
>> Chris, any thought? I wouldn't want to impose the change of name if it  
>> is
>> typical in most software APIs, but I am sensitive to the points made by  
>> Ray
>> and Philip.
>>
>
> This is one method in a family of methods which include "AtTime" in their
> name:
>
> setValueAtTime()
> linearRampToValueAtTime()
> exponentialRampToValueAtTime()
> setTargetValueAtTime()
> setValueCurveAtTime()
>
> So I think it's important to maintain consistency here.  Also, I believe
> the name describes precisely what it does.  In other words, the "target
> value" is set at the time given (which for all the methods is the time of
> the event in the time-ordered event list):
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#methodsandparams-AudioParam
>

Once you understand what the function does, the name makes sense. However,  
the name alone does not make it easy to understand what it does.

I think that the confusion (at least for me) is that "setTargetValue" is  
very similar to "setValue", and I fear that many will have them mixed up.  
Generally speaking, the "set" term indicates a zero-duration operation.  
I'd much rather see that methods that cause gradual changes use a  
consistent naming convention, excluding the term "set".

I think that a more appropriate name could be "approachValueAtTime" or  
"startApproachingValueAtTime".

Similarly the name "setValueCurveAtTime" would do better without "set".  
Any suggestions? (I'm out of ideas right now)


/Marcus


-- 
Marcus Geelnard
Core Graphics Developer
Opera Software ASA

Received on Friday, 29 June 2012 08:20:51 UTC