Commenting and Indentation

---

Comments

Every file (.c or .h) should start with a comment of few lines.

   /* Name: Fibonacci.c
      Creator: Foolan Barik (foobar@iitkgp.ac.in)
      Date: July 24, 2007
      Description: In this file 108 ways of computing Fibonacci numbers are implemented
   */

Every function should also be preceded by a comment of few lines.

   /* Name: linearDnC()
      Input: n - a non-negative integer
      Output: The n-th Fibonacci number F(n)
      Description: This program uses a divide-and-conquer recursion for
         computing Fibonacci numbers in linear time. It is based on the
         formula: F(m+n) = F(m+1)F(n)+F(m)F(n-1).
   */
   
   int linearDnC ( int n )
   {
       int t1, t2, t3; /* Temporary variables storing smaller Fibonacci numbers */
      
       /* n must be non-negative */
       if (n < 0) return -1;
      
       /* Basis cases */
       if (n == 0) return 0;
       if (n == 1) return 1;
       if (n == 2) return 1;
      
       /* Recursive calls on two subproblems of half size */
       t1 = linearDnC(n/2);
       t2 = linearDnC(n/2+1);
      
       /* Case 1: n is odd */
       if (n & 1) return t1*t1+t2*t2;
      
       /* Case 2: n is even */
       t3 = t2 - t1;
       return t1*(t2+t3);
   }

Put comments elsewhere also in order to enhance the legibility of your code. It is not advisable to flood your program with comments. For example, you have no need to write

/* increment i */

against ++i;. That is obvious! Mark important points only. For an example, look at the comments given in the above function.

---

Indentation

You should learn how to indent a C program. Properly indented programs are legible, promote easier debugging and provide protection against certain queer compilation errors. In this article, the Kernighan-Ritchie style of indentation is followed. Click here for more information.

Indentation does not only mean that a few lines of your code leave extra blank spaces on their left. Certain conventions regarding these spaces are necessary for this indentation to be a proper indentation. This also includes proper placement of the curly braces ({ and }). A sequence of C statements enclosed within a matching pair of braces is called a block.

Fix an indentation amount for your codes. In industry, people usually use a tab as the indentation amount. Since a tab (normally) means eight characters, programs with large levels of nesting of blocks may face difficulty with such a large indentation amount. You may instead use 3 or 4 spaces as the indentation amount.

• Indenting functions: Every function requires a block, namely the body of the function. In the first line write the return type (optional), the name and the list of parameters (within parentheses). In the second line write only the opening brace {. In the next line start the body of the function. Every line in the body will receive an indentation of the amount you decided earlier. After the body write the closing brace in a single line.

  #include <stdio.h>
  #include <stdlib.h>
  #include <math.h>
  #include <time.h>
  #include "mydefs.h"
  
  float myRoutine ( int n , float f )
  {
      int k;
  
      Leave the indentation amount
      in every line
      inside this block.
      ...
      ...
      ...
  
      return(3.1415926535);
  }
  
  mySecondRoutine ( )
  {
      Declare variables
      Declare variables
      Declare variables
  
      Indented instruction
      Indented instruction
      ...
      Indented instruction
  }
  
  int main ( int argc , char *argv[] )
  {
      Declare variables
      Declare variables
      Declare variables
      Declare variables
  
      Indented instruction
      Indented instruction
      ...
      Indented instruction
  }
  

• Nested blocks: Conditional statements (if, else) and loops (for, while, do etc.) with multiple instructions require blocks. Here write the condition and the opening brace on the same line. Then give an additional indentation of the chosen amount for each line inside the block. Finally write the closing brace in a single line without the extra indentation inside the block. Thus every nesting of block incurs additional indentation inside the block. A one-line if (or for or while or ...) statement can be thought of as a block with invisible enclosing braces. This is demonstrated below.

  #include <stdio.h>
  
  int fibonacci1 ( int n )
  {
      if (n < 0) {
          printf("Error: Non-negative argument expected.\n");
          return(-1);
      }
      if (n <= 1) return (n);
      else
          return (fibonacci1(n-1) + fibonacci1(n-2));
  }
  
  int fibonacci2 ( int n )
  {
      int this, prev, next, i;
  
      if (n < 0) {
          printf("Error: Non-negative argument expected.\n");
          return(-1);
      }
      if (n == 0) return (0);
      prev = 0;
      this = 1;
      for (i=2; i<=n; i++) {
          next = this + prev;
          prev = this;
          this = next;
      }
      return (this);
  }
  
  int main ()
  {
      int response, n, fibn;
  
      while (1) {
          printf("\n\n");
          printf("Enter 1 for calling the recursive function,\n");
          printf("      2 for calling the iterative function,\n");
          printf("      0 to terminate.\n");
          printf("Your choice : ");
          scanf("%d",&response);
          /* Echo response for printout */
          if (response == 0) exit(0);
          if ( (response == 1) || (response == 2) ) {
              printf("n = ");
              scanf("%d",&n);
              /* Echo n for printout */
              if (response == 1) {
                  printf("Calling the recursive function...\n");
                  fibn = fibonacci1(n);
              } else {
                  printf("Calling the iterative function...\n");
                  fibn = fibonacci2(n);
              }
              printf("Fib(n) = %d\n", fibn);
          }
      }
  }
  

---

Lab home

My home