Fibonacci Example for the SSU CS Style Guide for C/C++

Code

/** ***************************************************************************
 * @remark computation and timing of elements of the Fibonnaci sequence       *
 *  using the basic recurisve formula for the sequence                        *
 *  with and without dynamic prog.                                            *
 *                                                                            *
 * @author Henry M. Walker                                                    *
 * @file  fibonacci.c                                                         *
 * @date  August 14, 2022                                                     *
 *                                                                            *
 * @remark References                                                         *
 * @remark Dynamic Programming:  Anany Levitin, "The Design and               *
 *         and Analysis of Algorithms", Second Edition,                       *
 *         Chapter 8:  Dynamic Programming                                    *
 * @remark Dynamic Programming:  Anany Levitin, "The Design and               *
 *         and Analysis of Algorithms", Second Edition,                       *
 *         Section 2.5:  Example: Computing the nth Fibonacci Number          *
 *                                                                            *
 * @remark People participating with Problem/Progra Discussions:              *
 *         None                                                               *
 *                                                                            *
 *****************************************************************************/

#include <stdio.h>
#include <time.h>     // for time

Commentary

/** designates the beginning of an annotation for use in Doxygen.
- whitespace is needed after the second asterisk.
- If a line of astericks is desired at the start of a comment block, leave 1 space after the second asterisk before completing the line.
- Doxygen does not copy entire lines of asterisks (e.g., at the beginning or end of an annotation.)
- However, Doxygen does include individual asterisks within a line of text.
The @remark tag tells Doxygen that a comment follows.
- The comment continues until a blank line or the next tag
- If two or more @remark tages, commentary for each tage starts on a new line.
- Initial comments identify purpose of program
- The author, file, and date tags tell Doxygen to use specified labels and formatting
- Comment for time.h indicates function required from this library

/** ***************************************************************************
 * compute the nth fibonacci number directly,                                 *
 * using the recursive definition of the sequence                             *
 * @param  n:  the nth Fibonacci number to be computed                        *
 *              (starting the sequence at index 0)                            *
 * @pre   0 <= n                                                              *
 * @returns  the nth Fibonacci number                                         *
 *****************************************************************************/
nt fibSeq1(int n) {
  if (n <= 1 ) {
    return 1;
  }
  else {
    return fibSeq1 (n-1) + fibSeq1 (n-2);
  }
}

The block for a function can combine two forms
- use a rectangle of asterisks, in the style of a text box
- leave a space after the second asterisk of the opening line, as required by Doxygen.
A function header identifies
- purpose of function
- clarification of parameter n, with a @param tag
- clarification of pre-condition for n, with a @pre tag
- identification of value returned, with a @returns tag
- in each case, the ampersand @ is needed for Doxygen
Although the if and else control only one statement, braces are still used for consistency and to ease the addition of additional statements later.

/** ***************************************************************************
 * helper function to compute the nth fibonacci number,                       *
 * using the recursive definition and dynamic programming                     *
 * @param  n:  the nth Fibonacci number to be computed                        *
 *              (starting the sequence at index 0)                            *
 * @param  fibArr:  an initialize array, recording                            *
 *              Fibonacci numbers already computed                            *
 * @pre   0 <= n <= 1 + length of fibArr array                                *
 * @returns  the nth Fibonacci number                                         *
 *****************************************************************************/
int fibSeq2Helper (int n, int fibArr [ ]) {
  if (fibArr[n] != 0) {
    return fibArr[n];
  }
  if (n <= 1) {
    return fibArr[n] = 1;
  }
  else {
    return fibArr[n] = fibSeq2Helper (n-1, fibArr)
                       + fibSeq2Helper (n-2, fibArr);
  }
}

As noted above, to include comments in Doxygen document, start header with /** and a space for Doxygen. Complete the line with asterisks for a text-based box format.
function header identifies
- purpose of function
- clarification of parameter n, with a @param tag
- clarification of parameter fibArr, with a @param tag
- clarification of pre-condition for n, with a @pre tag
- identification of value returned, with a @returns tag
Braces are used to clarify the scope of both the if and else, and to allow the easy addition of further statements.

/** ***************************************************************************
 * compute the nth fibonacci number,                                          *
 * using the recursive definition and dynamic programming                     *
 * @param  n:  the nth Fibonacci number to be computed                        *
 *              (starting the sequence at index 0)                            *
 * @pre   0 <= n                                                              *
 * @returns  the nth Fibonacci number                                         *
 *****************************************************************************/
iint fibSeq2 (int n) {
  //create an initialized local array for bookkeeping before recursing
  int arr [n+1];
  for (int i = 0; i <= n; i++) {
     arr[i] = 0;
  }
  return fibSeq2Helper (n, arr);
}

The function header itself identifies
- purpose of function
- clarification of parameter n, with a @param tag
- clarification of pre-condition for n, with a @pre tag
- identification of value returned, with a @returns tag
Comment clarifies the purpose of the arr array, as a structure for dynamic programming
Braces are used to highlight the scope of the for loop, even though the loop body contains only one statement. These braces alwo allow the easy addition of further statements within the loop.

/** ***************************************************************************
 * main procedure controls computation, timing, and printing                  *
 *****************************************************************************/
int main ( ) {
  int reps = 100;  // number of times call repeated to help timings
  
  printf ("timing of two functions to compute the nth Fib number\n");
  printf ("    (each function call repeated %d times)\n", reps);
  printf ("               Approach 1          Approach 2\n");
  printf ("     n      Fib[n]     time    Fib[n]     time\n");

  // variables used for loops and timing
  int n;
  int value;
  clock_t start_time, end_time;
  double elapsed_time;

  for (n = 1; n <= 45; n += 4) {
    printf ("%6d", n);

    // time first approach
    start_time = clock ();
    for (int j = 0; j < reps; j++)
      value = fibSeq1 (n);
    end_time = clock();
    elapsed_time = (end_time - start_time) / (double) CLOCKS_PER_SEC;
    printf ("%11d   %6.1lf", value, elapsed_time);

    // time second approach
    start_time = clock ();
    for (int k = 0; k < reps; k++)
      value = fibSeq2 (n);
    end_time = clock();
    elapsed_time = (end_time - start_time) / (double) CLOCKS_PER_SEC;
    printf ("%11d   %6.1lf\n", value, elapsed_time);
  }
}

Initial comment identifies primary scope of the main procedure

Comment for reps briefly describes purpose of variable

Text within printf clarifies purpose of output—no need to say more

Comments identify two sections of code, which handle timing

fibonacci.c: Annotated Example of C Code, written for CS 415, Following the SSU CS Style Guide for C/C++

Code

Commentary

`fibonacci.c`: Annotated Example of C Code, written for CS 415,
Following the SSU CS Style Guide for C/C++