This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 18332 - Node creation method naming inconsistencies
Summary: Node creation method naming inconsistencies
Status: CLOSED FIXED
Alias: None
Product: AudioWG
Classification: Unclassified
Component: Web Audio API (show other bugs)
Version: unspecified
Hardware: PC Linux
: P2 normal
Target Milestone: TBD
Assignee: Chris Rogers
QA Contact: public-audio
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2012-07-19 13:40 UTC by Marcus Geelnard (Opera)
Modified: 2013-04-25 15:31 UTC (History)
1 user (show)

See Also:


Attachments

Description Marcus Geelnard (Opera) 2012-07-19 13:40:33 UTC
http://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioContext-section

The methods for creating different AudioNodes use inconsistent naming conventions. Here is a list of current method -> type mappings:

createBufferSource -> AudioBufferSourceNode
createMediaElementSource -> MediaElementAudioSourceNode
createMediaStreamSource -> MediaStreamAudioSourceNode
createJavaScriptNode -> JavaScriptAudioNode
createAnalyser -> RealtimeAnalyserNode
createGainNode -> AudioGainNode
createDelayNode -> DelayNode
createBiquadFilter -> BiquadFilterNode
createPanner -> AudioPannerNode
createConvolver -> ConvolverNode
createChannelSplitter -> AudioChannelSplitter
createChannelMerger -> AudioChannelMerger
createDynamicsCompressor -> DynamicsCompressorNode
createOscillator -> Oscillator

Apart from the inconsistently named AudioNode interfaces (see Bug 17407), the constructors also use a fair mix of:

* Complete interface name, e.g. createDelayNode and createOscillator
* With Node suffix, e.g. createGainNode, createDelayNode
* Without Node suffix, e.g. createBufferSource, createConvolver
* With key parts of the name dropped, e.g. createAnalyzer

The only consistency I can see is that any occurrences of "Audio" in the interface names have been dropped in the create-method names.

Suggestion: Include the entire interface name, possibly excluding Audio prefix and/or Node suffix (as long as it's the same for all methods).
Comment 1 Chris Rogers 2012-10-02 21:24:12 UTC
(In reply to comment #0)
> http://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioContext-section
> 
> The methods for creating different AudioNodes use inconsistent naming
> conventions. Here is a list of current method -> type mappings:
> 
> createBufferSource -> AudioBufferSourceNode
> createMediaElementSource -> MediaElementAudioSourceNode
> createMediaStreamSource -> MediaStreamAudioSourceNode
> createJavaScriptNode -> JavaScriptAudioNode
> createAnalyser -> RealtimeAnalyserNode
> createGainNode -> AudioGainNode
> createDelayNode -> DelayNode
> createBiquadFilter -> BiquadFilterNode
> createPanner -> AudioPannerNode
> createConvolver -> ConvolverNode
> createChannelSplitter -> AudioChannelSplitter
> createChannelMerger -> AudioChannelMerger
> createDynamicsCompressor -> DynamicsCompressorNode
> createOscillator -> Oscillator
> 
> Apart from the inconsistently named AudioNode interfaces (see Bug 17407), the
> constructors also use a fair mix of:
> 
> * Complete interface name, e.g. createDelayNode and createOscillator
> * With Node suffix, e.g. createGainNode, createDelayNode
> * Without Node suffix, e.g. createBufferSource, createConvolver
> * With key parts of the name dropped, e.g. createAnalyzer
> 
> The only consistency I can see is that any occurrences of "Audio" in the
> interface names have been dropped in the create-method names.
> 
> Suggestion: Include the entire interface name, possibly excluding Audio prefix
> and/or Node suffix (as long as it's the same for all methods).

How about being consistent by removing the "Node" suffix, leaving all the "create" methods the same, except for:

createGainNode -> createGain
createDelayNode -> createDelay

createJavaScriptNode -> createScriptProcessor

I'm less sure about the naming of "createScriptProcessor".  Some have suggested that we might use other scripting languages than JavaScript, so that shouldn't be a part of the name.
Comment 2 Marcus Geelnard (Opera) 2012-10-03 07:07:26 UTC
(In reply to comment #1)
> How about being consistent by removing the "Node" suffix, leaving all the
> "create" methods the same, except for:
> 
> createGainNode -> createGain
> createDelayNode -> createDelay
> 
> createJavaScriptNode -> createScriptProcessor
> 
> I'm less sure about the naming of "createScriptProcessor".  Some have suggested
> that we might use other scripting languages than JavaScript, so that shouldn't
> be a part of the name.

I think we need to resolve Bug 17407 before moving forward with this one.
Comment 3 Chris Rogers 2012-10-16 20:11:05 UTC
(In reply to comment #2)
> (In reply to comment #1)
> > How about being consistent by removing the "Node" suffix, leaving all the
> > "create" methods the same, except for:
> > 
> > createGainNode -> createGain
> > createDelayNode -> createDelay
> > 
> > createJavaScriptNode -> createScriptProcessor
> > 
> > I'm less sure about the naming of "createScriptProcessor".  Some have suggested
> > that we might use other scripting languages than JavaScript, so that shouldn't
> > be a part of the name.
> 
> I think we need to resolve Bug 17407 before moving forward with this one.

Now that 17407 is resolved, how do the two method name-changes sound?
Comment 4 Marcus Geelnard (Opera) 2012-10-17 07:13:38 UTC
(In reply to comment #3)
> Now that 17407 is resolved, how do the two method name-changes sound?

Given your suggestion, we'd get:

createBufferSource -> AudioBufferSourceNode
createMediaElementSource -> MediaElementAudioSourceNode
createMediaStreamSource -> MediaStreamAudioSourceNode
createScriptProcessor -> ScriptProcessorNode
createAnalyser -> AnalyserNode
createGain -> GainNode
createDelay -> DelayNode
createBiquadFilter -> BiquadFilterNode
createWaveShaper -> WaveShaperNode
createPanner -> PannerNode
createConvolver -> ConvolverNode
createChannelSplitter -> ChannelSplitterNode
createChannelMerger -> ChannelMergerNode
createDynamicsCompressor -> DynamicsCompressorNode
createOscillator -> OscillatorNode

This looks very intuitive to me. The only thing sticking out here are the three first nodes, where "Audio" is somehow in the node name (which seems right IMO), but not in the create* method name.

I don't have any objections to that (shorter names = good thing™), other than the possible loss of distinction between Audio/Video Media sources that you mentioned in Bug 17407. Any thoughts?
Comment 5 Chris Rogers 2012-10-17 21:40:39 UTC
(In reply to comment #4)
> (In reply to comment #3)
> > Now that 17407 is resolved, how do the two method name-changes sound?
> 
> Given your suggestion, we'd get:
> 
> createBufferSource -> AudioBufferSourceNode
> createMediaElementSource -> MediaElementAudioSourceNode
> createMediaStreamSource -> MediaStreamAudioSourceNode
> createScriptProcessor -> ScriptProcessorNode
> createAnalyser -> AnalyserNode
> createGain -> GainNode
> createDelay -> DelayNode
> createBiquadFilter -> BiquadFilterNode
> createWaveShaper -> WaveShaperNode
> createPanner -> PannerNode
> createConvolver -> ConvolverNode
> createChannelSplitter -> ChannelSplitterNode
> createChannelMerger -> ChannelMergerNode
> createDynamicsCompressor -> DynamicsCompressorNode
> createOscillator -> OscillatorNode
> 
> This looks very intuitive to me. The only thing sticking out here are the
> three first nodes, where "Audio" is somehow in the node name (which seems
> right IMO), but not in the create* method name.
> 
> I don't have any objections to that (shorter names = good thing™), other
> than the possible loss of distinction between Audio/Video Media sources that
> you mentioned in Bug 17407. Any thoughts?

My thinking here was that the create() methods are in the "namespace" of the AudioContext, and thus it's implied that we're dealing with audio, and the clarity gained by the shorter name was worth it.  By contrast, the node/class names are in the global namespace and so I wanted to make that distinction.
Comment 6 Marcus Geelnard (Opera) 2012-10-18 07:50:45 UTC
(In reply to comment #5)
> My thinking here was that the create() methods are in the "namespace" of the
> AudioContext, and thus it's implied that we're dealing with audio, and the
> clarity gained by the shorter name was worth it.  By contrast, the
> node/class names are in the global namespace and so I wanted to make that
> distinction.

Ah, good point. Looks fine to me.
Comment 7 Chris Rogers 2012-11-14 21:32:36 UTC
Fixed:
https://dvcs.w3.org/hg/audio/rev/233781dbb864
Comment 8 Marcus Geelnard (Opera) 2012-11-15 08:10:45 UTC
Looks good. A minor miss though: createGainNode is still being used in an example (1.2. Modular Routing).

By the way, should appendix C (Web Audio API Change Log) still be maintained or should it be dropped? It seems to lack most recent updates.
Comment 9 Olivier Thereaux 2012-11-19 16:08:30 UTC
(In reply to comment #8)
> By the way, should appendix C (Web Audio API Change Log) still be maintained
> or should it be dropped? It seems to lack most recent updates.

I gather it's updated only when we do a /TR publication. The up-to-date changelog remains http://dvcs.w3.org/hg/audio/ (which, admittedly, also includes the change log for our other docs)
Comment 10 Marcus Geelnard (Opera) 2012-12-10 11:33:00 UTC
Setting to reopened, since section 1.2. is still wrong (see https://www.w3.org/Bugs/Public/show_bug.cgi?id=18332#c8 ).
Comment 11 Olivier Thereaux 2013-04-04 14:37:36 UTC
(In reply to comment #8)
> Looks good. A minor miss though: createGainNode is still being used in an
> example (1.2. Modular Routing).

I have spun off Bug #21580 to track this particular issue. 

Closing here.