(A few days back I was again referring to my old post Comments are not Code when talking with my coworker. I published that post some time ago at my former blog and to make it more accessible I'm republishing it here.) I'm a firm believer that the best software documentation is the running code. If the code is well structured and written, it speaks for itself and it does not need any additional documentation. Comments are not code and therefore should not be used where better code organization would suffice.
A 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:
[sourcecode language="python"] def check_specific_candidate():
# first check if we already have X by any chance < 10 lines of code, return if true >
# Try out if candidate is Y < 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 > [/sourcecode]
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:
[sourcecode language="python"] 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) [/sourcecode]
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.