Grading Criteria python Context

From A-State Computer Science Wiki
Jump to: navigation, search

Design

Programs should be developed using a top-down design approach. A moderate amount of thought and work each day will produce meaningful and useful debug and checkout information. Start with a high-level, English-like pseudocode in order to avoid becoming too concerned with dealing with too much detail too soon. This reduces the probability of overlooking important considerations that would cause one to have to redesign and rewrite code.

Modularity

Each program shall utilize "structured programming" techniques and so be modular in nature. This means in part that no unstructured elements (e.g. goto, continue, exit, etc.) are to be used. Each function shall have one entry point and one exit point; in particular, there should only be a single return point in a function, and it should be at the bottom. Each function should be dedicated to performing a particular task and be named accordingly. Consequently, functions will be relatively small, consisting of as little as one or two lines but no more than one screen of program code. Global references to identifiers are generally to be avoided. Function definitions should be located at the beginning of the program file following any import statements. Driver code should go after all function definitions.



Your program should follow the following structure:

  1. Comment block
  2. import statements
  3. initialize constants
  4. function definitions
  5. Driver Code (init vars, function calls, input/output, etc.)


User-Orientation

The format of the input data should be specified in the commenting of the program. Output should be clearly labeled and readable; it should also be arranged for eye-appeal using appropriate headings and alignments. A message should be written at the beginning of a program’s execution stating the name of the programmer, the assignment number, and a brief description of the program. A message should also be written at the end of a program’s execution indicating that a normal termination has taken place.

Documentation

  1. The file containing the start of execution should contain the following comment block:
    #*******************************************************************************
    #
    # Programmer: your name
    #
    # Assignment: filename specified in assignment instructions
    #
    # Description: general comments about what this file contains, and how it is 
    #              intended to be used
    #
    #*******************************************************************************
    
  2. Each function should contain the following three types of documentation:
    1. Prologue: This should include the purpose and a brief description of how to use the function. It should specify any input and output external to the program. It should also specify data flow into and out of the function both by way of the parameter list and return statement. These descriptions should be addressed to a user who wants to use the function but not read the code. The following format should be used:
      #*******************************************************************************
      # function_name
      #
      # description: purpose & how-to-use comments
      #
      # input:       if the function is using input external to the program, include 
      #              this section explaining what input is needed
      #
      # output:      if the function produces external output, include this section 
      #              explaining what output is produced
      # 
      # parameters:  list each parameter's name and a description of what it is used
      #              for here
      # 
      # returns:     if the function returns a value, explain what the value is and 
      #              how it might be used here
      #*******************************************************************************
      
    2. Definitions of Variables: When an identifier is introduced in a function, its purpose should be explained in a comment immediately to the right of its introduction.
    3. Interspersed Comments: Every logical step of the function should be documented to explain the purpose of the step with respect to the algorithm performed by the function. Some logical steps will require only one line of program code, while others will consist of several statements. The commenting for a logical step should precede the step.
  3. Follow every else with a comment indicating the negation of the corresponding if; this will serve to check your thinking with respect to the condition used; see below.
  4. Avoid repetition in comments; say something the program code does not. For example,
    balance = balance + credit # make deposit to account
    

    is preferable to

    balance = balance + credit # add balance and credit
    

Readability

  1. Indentation of code indicates the control structure of the program. In particular, the contents of a compound statement should be indented as shown below. Once an indentation style is adopted, it should be used consistently throughout the program. The following are some examples of acceptable indentation; note the placement of comments. It is advisable to use spaces for indentation in Python, not tabs (the width of tabs may vary from one system to another), and you should never mix spaces and tabs.
    import math
    
    if (inStock > orderAmount):
        print("sufficient quantity on hand")
    else: # inStock <= orderAmount
        print("place order immediately")
    
    if c > 0:
        a = b + c
        j += 1
        # end if
    
    x = 1
    while (error > 0.01):
        y = math.sqrt(x)
        error = f(x) + g(y) - 7
        x = x + 10
        # end while error is too large
    
    # naive bubblesort for "items"
    i = 0
    while i <= items_size - 2:          # each items[i] becomes next smallest
                                        # (last item in place by default)
        j = i + 1
        while j <= items_size - 1:      # begin search immediately following i
            if (items[j+1] < items[j]): # found something smaller
                temporary = items[j]    # swap items[j+1] with items[j]
                items[j] = items[j+1]
                items[j+1] = temporary
                # end if
            j = j + 1                   # look at next pair
            # end while more items
        i = i + 1                       # start next pass
        # end while more passes needed (i)
    
  2. Use blanks liberally to make code more easily readable. For example, the expression a = b * c + d / e is preferable to a=b*c+d/e.
  3. The above comment blocks contain a line of asterisks (*) with the last asterisk located in the 80th character column. A width of 80 is still an industry standard. Your code should not exceed 80 characters per line.
  4. If a statement is too long for the current line, continue writing the statement on the next line, but at an indentation level which reflects the context of the indentation. If still not enough space is available, continue to the next line at an appropriate indentation level until the statement is completed. In Python, you must use the character "\" to indicate that the statement continues on multiple lines. As an exaggerated example:
    a = variableB * variableC \
        - variableD * variableE *(6.31245 / (b - d * pi + pressure)) \
        - volume_of_gas / length_of_side + rate * time - e
    
  5. Variable names should be meaningful. Variable names such as a, b, and c are not acceptable when names such as mass, velocity, and currentBalance describe more accurately the intended meaning associated with the variable.
  6. Declaration of variables should be in an eye-appealing format.

Coding Rules

  1. Use constants for those values which will not change throughout the execution of the program. Examples might include SALES_TAX_RATE, ORCHESTRA_SEAT_TICKET_PRICE, etc.
  2. The use of goto and continue is not allowed; return should only appear once within a function, at the bottom.
  3. Tricky code should be avoided in favor of readable, straight-forward code; try to imagine how it will read to you after several months have passed without looking at it.
  4. No more than one statement should be placed on a line.
  5. Do not make an equality comparison such as
    a == b
    

    upon variables of a floating point data type; instead, use a tolerance test such as

    abs(a - b) < 0.0001
    
  6. Avoid using the digit zero '0' in a variable name as it is easily confused with the letter 'O'.
  7. Avoid the use of global variables.