title: C API Design Questions - function names and semantics
body: <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>