Image by Richard Masoner / Cyclelicious via FlickrA misplaced use of comments that I often see while doing code reviews is to use comments to divide a method into logical subunits. For example:
def check_specific_candidate():
# first check if we already have X by any chance
< 10 lines of code, return if true>< 30 lines of code, return if true>
# candidate is not Y, try out if it is Z
< another 30 lines of code, return if true> # construct a list of elements in the candidate
< another 30 lines of code>
if len(list_of_elements) > 0:
# process list of elements for the candidate
< another 10 lines of code>
This example is based on actual routine in Zemanta code base that is altogehter 140 lines long. Supporting such code is not a nice experience. While comments in this routine do help, they are actually a symptom of a larger problem, i.e. poor code organization. Comments would immediately become redundant, if this routine would be split into logical steps with each step being a separate routine. Let's refactor the above routine as such:
def check_specific_candidate(candidate):
if _candidate_has_X(candidate):
return
if _candidate_is_Y(candidate):
return
if _candidate_is_Z(candidate):
return
list_of_elements = _get_list_of_elements(candidate)
if len(list_of_elements) > 0:
_process_list_of_elements(list_of_elements)
So instead of using comments, this routine is now documented using method names. When you approach such code for the first time, seeing such nice 15-lines long routine is much less stressful than seeing a 140-lines long monster.
