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.