COMP 530: Lab Style Guide

Writing code with good style means that someone else should be able to be read and understood the intent behind your code. This "someone else" can often be you at a later point, needing to come back and understand what's going on, make changes, or extend functionality. For the purposes of grading, Style is split into 5 parts: compiler warnings, formatting, documentation, mechanics, and style. 1 point is assigned to each and then scaled to an appropriate percentage of the assignment grade.

What follows is a description of each graded part.

• Compiler Warnings: This is simple. The number of compiler warnings will be counted and points will be taken off for each of them. The gcc option -Wall causes all compiler warnings to be generated, and -Werror causes all compiler warnings to be treated as errors. Errors stop compilation, so if the program compiles with the -Wall and -Werror flags (which it will if make is used) the program will get full points for this part.
• Formatting: This is one of the more subjective pieces, but if the program follows one of the following styles (or something similar) it should get full points. Hint: Most of the starter code includes file-local variables for emacs and vim; if you use one of these editors, style issues should "just work".
• Documentation: There should be a comment for each file and for each function describing the purpose and use of it. Variable and function names should be self-documenting, and there should be enough comments to state how each subsection of a program works. Also be aware that having too many comments can obfuscate the structure of the code, so it is important to find the right balance. I find that at most one comment per three or four lines of code generally doesn't look too bad, but a program probably shouldn't need that many comments.
• Mechanics: In this part, programs are checked to make sure that they are following proper mechanical procedures. For instance, the program should be initializing variables, checking for NULL (or other errors) in function arguments and returns, using loops and conditonals properly, and using features like functions, structs, malloc, sizeof, and the like which will simultaneously improve code structure and ensure that the program won't have errors with unset variables. This is also the part where valgrind would be used to find the number of error contexts.
• Style: The main idea here is that the program not use anti-patterns like magic numbers. What will be checked for will be a subset of the issues described on the following pages: https://en.wikipedia.org/wiki/Anti-pattern#Software_engineering and https://en.wikipedia.org/wiki/Code_smell . Not all of these will be applicable to the programs in this class (notably the Object-oriented section in anti-pattern). In addition to this, programs will be penalized for commented out code. Granted, I will be looking at over 100 assignments, so I will not be able to check for all of these, but it is important to at least be aware of them.

Examples

Consider the following programs which create a simple ascii cipher table. They are functionally identical except for the fact that one uses a function call rather than putting everything in main. The first program has multiple instances of bad style, while the second one is cleaner. The second may not be the best way to write this particular piece of code, but it is more modular and extensible than the first.

//No file purpose and use comment (Documentation)
#define _GNU_SOURCE
#include 
#include 
#include 

int main(int argc, char ** argv){
  char ct[128]; //Magic Number Use (Style), bad variable name (Documentation)
  int i;
  for(i=0; i<128; i++){ //Magic Number Use (Style)
    ct[i]=127-i; //No comment on why this needs to be done (Documentation)
  }
  //The following comments say what the code is doing functionally, but don't
  //give an idea as to the reason that it's being done (Documentation)
  /* Randomizes the string */
  strfry(ct);
  /* sets i to random table position */
  i = rand()%128;
  //printf("%d\n", i); //Commented out line of code (Style)
  /* sets last character to character at i */
  ct[127] = ct[i];
  /* sets character at i to '\0' */
  ct[i] = '\0';
  for(i=0; i<128; i++){
  printf("%03d", ct[i]); //Non-indented line (Formatting)
  if(i!=127)
    printf(" "); //Defining specific behavior for the end of loop (Mechanics)
  }
  printf("\n");
}

/* This program generates an ascii cipher table and prints it to standard out.
 * Compile with make and run with ./cipherGen */
#define _GNU_SOURCE
#include 
#include 
#include 

#define asciiLength 128

char * genCipherTable(char * cipherTable);

int main(int argc, char ** argv){
  char * cipherTable = genCipherTable(NULL);
  int i;
  if(cipherTable == NULL)
    return -1;
  /* Prints cipherTable with a space between each character code followed by
   * a newline */
  printf("%03d", cipherTable[0]);
  for(i = 1; i < asciiLength; i++){
    printf(" %03d", cipherTable[i]);
  }
  printf("\n");
  free(cipherTable);
}

/* Either populates the existing cipherTable passed in as an argument or in
 * the case of a NULL arg, allocates space for a new table before populating it */
char * genCipherTable(char * cipherTable){
  int i;
  /* If no cipherTable was passed in, allocates space for one
   * Returns NULL on a failed allocation */
  if (cipherTable == NULL){
    cipherTable = malloc(asciiLength*sizeof(char));
    if (cipherTable == NULL)
      return NULL;
  }
  /* Fills cipherTable in reverse order. This is necessary because we are
   * passing it to strfry which needs a null-terminated string. We then
   * call strfry before swapping the null terminator with an arbitrary
   * element of the table, which is necessary for complete randomness. */ 
  for(i=0; i < asciiLength; i++){
    cipherTable[i]=(char) (asciiLength-1-i);
  }
  strfry(cipherTable);
  i = rand()%asciiLength;
  cipherTable[asciiLength-1] = cipherTable[i];
  cipherTable[i] = '\0';
  return cipherTable;
}

Acknowledgments

This style guide includes text from Jacob Fisher.

Last updated: 2018-11-20 17:38:17 -0500 [validate xhtml]