CSC 120: Bad Style Examples

Over-commenting

Comments are intended to communicate. Therefore, they should say something that is not obvious. Obviously, whether or not something is "obvious" depends on the reader—something that may be obvious to an expert may not be obvious to a novice. For the purposes of this class, we will consider the reader to be CSc 120 students like yourselves: i.e., with at least a basic understanding of Python.

When you write a comment, therefore, ask yourself whether the comment is saying something that would be obvious to a student in CSc 120.

Here is an example of over-commenting. The offending comments are shown in red.

def dictionary(lines): # this function is to create a 2d dictionary     types={} # create dictionary     info=[]  # create a list     for line in lines: # read file line by line         types[line[1].lower()]={"total":line[4],"hp":line[5],"attack":line[6],                 "defense":line[7],"specialattack":line[8],                 "specialdefense":line[9],"speed":line[10],                 "generation":line[11],"legendary":line[12]}# sort every information         info.append([line[1].lower(),line[2]]) # put the names and types together into a list     return types,info # return the list and dictionary def get_max_value(types,infor,query):     dictionary=database(types,infor,query)# this function calculates and prints the max value     data=[] # create a new list to save the sum and keys     max=0 # make max equals to 0     for keys,values in dictionary.items(): # use for loop to read dictionary         dictionary[keys]["sum"]=dictionary[keys]["sum"]/dictionary[keys]["num"] # divide sum by number to get average value         data.append([dictionary[keys]["sum"],keys]) # put the average value into new list     for j in range(1,len(data)): # use for loop to read data list         if(data[j][0]>data[max][0]): # check if the new one is the max value             max=j # set the new max value     print("{}:{}".format(data[max][1],data[max][0])) # print max value by given format

The code shown above has numerous other style problems; we'll go into details of other style issues elsewhere.

Here is the same code, with the uninformative comments removed. In their place I have placed comments, shown in blue, describing the overall effect of the for loops. In my opinion, getting rid of the uninformative comments removes visual clutter and improves the readability and understandability of the code.

def dictionary(lines): # this function is to create a 2d dictionary     types={}      info=[]       for line in lines:         types[line[1].lower()]={"total":line[4],"hp":line[5],"attack":line[6],                 "defense":line[7],"specialattack":line[8],                 "specialdefense":line[9],"speed":line[10],                 "generation":line[11],"legendary":line[12]}# sort every information         info.append([line[1].lower(),line[2]]) # put the names and types together into a list     return types,info def get_max_value(types,infor,query):     dictionary=database(types,infor,query)# this function calculates and prints the max value     data=[]     max=0     # compute the average value and put it into data     for keys,values in dictionary.items():         dictionary[keys]["sum"]=dictionary[keys]["sum"]/dictionary[keys]["num"]         data.append([dictionary[keys]["sum"],keys])     # compute the position of the maximum value for the average     for j in range(1,len(data)):         if(data[j][0]>data[max][0]):             max=j     print("{}:{}".format(data[max][1],data[max][0]))

When you write your code, please avoid over-commenting.