C API Design Questions - function names and semantics
<p>I am working on redesigning a simple C API interface for controlling a piece of hardware.</p>

<p>I have several questions that are all related to the API. I'm not sure if I should group them all in this question or submit multiple questions. For now I will list them all here.</p>

<p>For reference the API is structured in the following style.</p>

<pre><code>LIB_ERR_CODE myfunction1(int param1);
</code></pre>

<p>My questions:</p>

<ol>
<li><p>Is it more appropriate to have a function for Enable and Disable OR a single Enable function with a bool parameter?</p>

<pre><code>LIB_ERR_CODE EnableOscillator(int device);
LIB_ERR_CODE DisableOscillator(int device);
</code></pre>

<p>vs</p>

<pre><code>LIB_ERR_CODE EnableOscillator(int device, bool bEnable);
</code></pre></li>
<li><p>I want to unify the naming scheme. Below is some examples of the terms used. What are the preferred terms are?</p>

<p>Example 1:</p>

<pre><code>LIB_ERR_CODE SetTemperature(int value);    // set temperature
LIB_ERR_CODE GetTemperature(int *pvalue);  // returns actual temperature
</code></pre>

<p>Example 2:</p>

<pre><code>LIB_ERR_CODE ProgramHumidity(int value); // set humidity
LIB_ERR_CODE ReadHumidity(int *pvalue);  // returns actual humidity
</code></pre>

<p>Example 3:</p>

<pre><code>LIB_ERR_CODE WriteConfiguration(int value);   // write values to a config register
LIB_ERR_CODE ReadConfiguration(int *pvalue);  // reads values from the config register
LIB_ERR_CODE CurrentConfiguration(int *pvalue); // Current configuration values
</code></pre></li>
</ol>

<p>This is a piece of hardware I am communicating with so it makes sense to me for there to be three complementing functions. A function to set the value, a function to read back the set value, a function to read the actual value. </p>

<ol start="3">
<li><p>Is it logical to combine two function calls which are required to make 1 hardware feature operate? To set up the oscillator the following functions must be called (order doesn't matter).</p>

<pre><code>LIB_ERR_CODE ProgramFrequency(int freq);
LIB_ERR_CODE ProgramAmplitude(int amp);
</code></pre>

<p>I feel it would make more sense to combine them.</p>

<pre><code>LIB_ERR_CODE ProgramOscillator(int freq, int amp);
</code></pre></li>
</ol>