Successfully reported this slideshow.

No comment

2,062 views

Published on

Stop clarifying code with comment; write code clearly instead.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No comment

  1. 1. # No comment.
  2. 2. # Stop clarifying code with comments;
  3. 3. # Stop clarifying code with comments;# Write code clearly instead.
  4. 4. # Clarifying comments are not # documentation# Converts the object into textual markup given a specific `format`# (defaults to `:html`)## == Parameters:# format::# A Symbol declaring the format to convert the object to. This# can be `:text` or `:html`.## == Returns:# A string representing the object in a specified# format.#def to_format(format=:html) # format the objectend
  5. 5. # Clarifying comments are not # documentation# Converts the object into textual markup given a specific format.## @param [Symbol] format the format type, `:text` or `:html`# @return [String] the object converted into the expected format.def to_format(format = :html) # format the objectend
  6. 6. # Clarifying comments are not # legal statements# Copyright (C) 2012 by Nate Davis Olds. All rights reserved.# Released under the terms of the GNU General Public License version 2 or later.
  7. 7. # Clarifying comments are not # reminder notes# FIXME high priority for nextdeploydef process raise “n”end# OPTIMIZE refactor this code toget more donedef goodnight sleep 6.hoursend# TODO any other way to do this?def process(str=’inter’) “use “ + str + ”polation”end
  8. 8. # Clarifying comments are not # reminder notes# FIXME high priority for next $ rake notesdeploy (in /home/foobar/commandsapp)def process app/controllers/admin/users_controller.rb: raise “n”   * [ 20] [TODO] any other way to do this?end   * [132] [FIXME] high priority for next deploy# OPTIMIZE refactor this code to  get more done app/model/person.rb:def goodnight   * [ 13] [OPTIMIZE] refactor this code to get sleep 6.hours more doneend# TODO any other way to do this?def process(str=’inter’) “use “ + str + ”polation”end
  9. 9. # The attention of the comment # is outside the scope # of the accompanying code# used by rake for task management# TODO any other way to do this?def process(str=’inter’) “use “ + str + ”polation”end# used by yard # Converts the object into textual markup given a specific format. # # @param [Symbol] format the format type, `:text` or `:html` # @return [String] the object converted into the expected format. def to_format(format = :html) # format the object end# used by courts # Copyright (C) 2012 by Nate Davis Olds. All rights reserved. # Released under the terms of the GNU General Public License version 2 or later.
  10. 10. # A clarifying comment’s attention is# directed internally # inserts a string between two other strings def process(str=’inter’) “use “ + str + ”polation” end
  11. 11. # Clarifying comments are # explanations # of the code that follows.# inserts a string between two other stringsdef process(str=’inter’) “use “ + str + ”polation”end
  12. 12. # Clarifying comments are # redundant # of the code that follows.# inserts stringdef insert_string(str=’inter’) “use “ + str + ”polation”end
  13. 13. # Clarifying comments are # apologizes # of the code that follows.# This code sucks! I know it. You know it.# I am sorry that you have to read it.def is_this_example_good 100.times { ”No! it sucks!” }end# I’m drunk.def string_theory_patterns ...end
  14. 14. # Clarifying comments are # rants # of the code that follows.# At this point, Id like to take a moment to speak to you about the Adobe PSD# format. PSD is not a good format. PSD is not even a bad format. Calling it# such would be an insult to other bad formats, such as PCX or JPEG. No, PSD# is an abysmal format. Having worked on this code for several weeks now, my# hate for PSD has grown to a raging fire that burns with the fierce passion# of a million suns.#.....# Earlier, I tried to get a hold of the latest specs for the PSD file format.# To do this, I had to apply to them for permission to apply to them to have# them consider sending me this sacred tome. This would have involved faxing# them a copy of some document or other, probably signed in blood. I can only# imagine that they make this process so difficult because they are intensely# ashamed of having created this abomination. I was naturally not gullible# enough to go through with this procedure, but if I had done so, I would have# printed out every single page of the spec, and set them all on fire. Were it# within my power, I would gather every single copy of those specs, and launch# them on a spaceship directly into the sun.## PSD is not my favourite file format.
  15. 15. # Clarifying comments are # open letters # of the code that follows.# Dear maintainer:## Once you are done trying to optimize this routine,# and have realized what a terrible mistake that was,# please increment the following counter as a warning# to the next guy:## total_hours_wasted_here = 42#
  16. 16. # Clarifying comments are # warnings # of the code that follows.# After you run this code, take the day off.# It won’t finish until tomorrow.def im_compiling(stop_at=14.hours.from_now) if stop_at < Time.zone.now puts "done." else print "." sleep 10 im_compiling stop_at endend
  17. 17. # Clarifying comments are # dialogs # of the coder that follows.# This is brilliant!# Thanks. It’s nap time.def im_compiling(stop_at=14.hours.from_now) if stop_at < Time.zone.now puts "done." else print "." sleep 10 im_compiling stop_at endend
  18. 18. # Clarifying comments are # inside jokes # of the code that follows.stop() # hammertime
  19. 19. # Clarifying comments are # misleading descriptions # of the code that follows.# Returns the standard utility allowance# based on how many utilities someone pays.def standard_utility_allowance 324end
  20. 20. # Clarifying comments are # stashed codedef standard_utility_allowance # of the code that follows. 324 # Uncomment this by March 3, 2012 when estimations switch back # # case @answers[:utility_allowance] # # when Pays for Heating or # Cooling or receives MEAP or EUSP # 394.0 # # when "Doesnt pay for heating or cooling but pays two other utilities" # 239.0 # # when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" # @answers[:actual_utility_cost] # # when "Pays telephone only" # 40.0 # # else # 0.0 # endend
  21. 21. # Clarifying comments are # deserted code # of the code that follows.def standard_utility_allowance case @answers[:utility_allowance] when Pays for Heating or # Cooling or receives MEAP or EUSP 394.0# when "Doesnt pay for heating or cooling but pays two other utilities"# 239.0 when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" @answers[:actual_utility_cost] when "Pays telephone only" 40.0 else 0.0 endend
  22. 22. # Why should clarifying comments be removed?
  23. 23. # Why should clarifying comments be removed?# Clarifying comments are codejunk
  24. 24. # Why should clarifying comments be removed?# Clarifying comments are codejunk term from Katrina Owen # talk entitled Therapeutic Refactoring on confreaks from Cascadia Ruby Conference
  25. 25. # Why should clarifying comments be removed?# Clarifying comments are codejunk term from Katrina Owen # talk entitled Therapeutic Refactoring on confreaks from Cascadia Ruby Conference codejunk is a play from Edward Tufté term chartjunk 1 1 Tufte, Edward R. (1983). The Visual Display of Quantitative Information. Cheshire, CT: Graphics Press.
  26. 26. Chartjunk refers to all visual elements in charts andgraphs that are not necessary to comprehend theinformation represented on the graph, or thatdistract the viewer from this information.
  27. 27. Codejunk refers to all visual elements in code thatare not necessary to comprehend the informationrepresented in the code, or that distract the viewerfrom this information.
  28. 28. Understanding Code70% New Code 5% Modifying Existing Code 25%# http://blogs.msdn.com/b/peterhal/archive/2006/01/04/509302.aspx Peter Hallam
  29. 29. # Why should clarifying comments be removed?
  30. 30. # Why should clarifying comments be removed?Because we spend most ofour time reading andunderstanding code
  31. 31. # Isn’t that why we write clarifying comments?
  32. 32. # Isn’t that why we write clarifying comments?No. We write clarifyingcomments because our codeisn’t clear enough.
  33. 33. The use of a clarifyingcomment admits the failureto write readable, clean code
  34. 34. The use of a clarifyingcomment admits the failureto write readable, clean code # Stop clarifying code with comments; # Write code clearly instead.
  35. 35. # explanations
  36. 36. # explanations # inserts a string between two other strings def process(str=’inter’) “use “ + str + ”polation” end
  37. 37. # explanations # inserts a string between two other strings def process(str=’inter’) “use “ + str + ”polation” end# rename function def insert_string(str=’inter’) “use “ + str + ”polation” end
  38. 38. # redundant comment
  39. 39. # redundant comment # inserts string def insert_string(str=’inter’) “use “ + str + ”polation” end
  40. 40. # redundant comment # inserts string def insert_string(str=’inter’) “use “ + str + ”polation” end# without comment def insert_string(str=’inter’) “use “ + str + ”polation” end
  41. 41. # apologizing
  42. 42. # apologizing # This code sucks! I know it. You know it. # I am sorry that you have to read it. def is_this_example_good 100.times { ”No! it sucks!” } end
  43. 43. # apologizing # This code sucks! I know it. You know it. # I am sorry that you have to read it. def is_this_example_good 100.times { ”No! it sucks!” } end# make it better def is_this_example_good 1000.times { ”Awesome” } end
  44. 44. # rants
  45. 45. # rants# At this point, Id like to take a moment to speak to you about the Adobe PSD# format. PSD is not a good format. PSD is not even a bad format. Calling it# such would be an insult to other bad formats, such as PCX or JPEG. No, PSD
  46. 46. # rants# At this point, Id like to take a moment to speak to you about the Adobe PSD# format. PSD is not a good format. PSD is not even a bad format. Calling it# such would be an insult to other bad formats, such as PCX or JPEG. No, PSD# blog about it. tweet it. Or give a presentation about it. Just Remove it from code.Why I hate Adobe PSD format!by I. RantAt this point, Id like to take a moment to speak to you about the Adobe PSDformat. PSD is not a good format. PSD is not even a bad format. Calling itsuch would be an insult to other bad formats, such as PCX or JPEG. No, PSD
  47. 47. # Open letters
  48. 48. # Open letters # Dear maintainer: # # Once you are done trying to optimize this routine, # and have realized what a terrible mistake that was, # please increment the following counter as a warning # to the next guy: # # total_hours_wasted_here = 42 #
  49. 49. # Open letters # Dear maintainer: # # Once you are done trying to optimize this routine, # and have realized what a terrible mistake that was, # please increment the following counter as a warning # to the next guy: # # total_hours_wasted_here = 42 ## Schedule a fix. State the problem. # OPTIMIZE: or refactor. The problem is....
  50. 50. # warnings
  51. 51. # warnings# After you run this code, take the day off.# It won’t finish until tomorrow.def im_compiling(stop_at=14.hours.from_now) if stop_at < Time.zone.now puts "done." else print "." sleep 10 im_compiling stop_at endend
  52. 52. # warnings# if it is meant to run long, warn at runtimedef im_compiling(stop_at=nil) if stop_at.nil? print “This will take 14 hours. Proceed? (y/n):” should_continue = STDIN.gets.chomp if should_continue == “y” im_compiling 14.hours.from_now end elsif stop_at < Time.zone.now puts "done." else print "." sleep 10 im_compiling stop_at endend
  53. 53. # warnings# schedule optimization# OPTIMIZE: remove the n+1 database callsdef comment_summaries_for_everyone summaries = [] Person.all.each do |person| person.posts.each do |post| post.comments.each do |comment| summaries << “#{comment.author_name}: #{comment.body}” end end end summariesend
  54. 54. # dialogs # This is brilliant! # Thanks. It’s nap time.
  55. 55. # dialogs # This is brilliant! # Thanks. It’s nap time.# email. chat. twitter. phone. how about talk?!?
  56. 56. # jokes
  57. 57. # jokes stop() # hammertime
  58. 58. # jokes stop() # hammertime# funny the first time, but does it need to be checked in? Delete it stop()
  59. 59. # misleading descriptions
  60. 60. # misleading descriptions # Returns the standard utility allowance # based on how many utilities someone pays. def standard_utility_allowance 324 end
  61. 61. # misleading descriptions # Returns the standard utility allowance # based on how many utilities someone pays. def standard_utility_allowance 324 end# Remove it or investigate what is correct. def standard_utility_allowance 324 end
  62. 62. # stashed codedef standard_utility_allowance 324 # Uncomment this by March 3, 2012 when estimations switch back # # case @answers[:utility_allowance] # # when Pays for Heating or # Cooling or receives MEAP or EUSP # 394.0 # # when "Doesnt pay for heating or cooling but pays two other utilities" # 239.0 # # when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" # @answers[:actual_utility_cost] # # when "Pays telephone only" # 40.0 # # else # 0.0 # endend
  63. 63. # stashed code# write it inline, set a note to clean it up# FIXME: After March 3, 2012def standard_utility_allowance if after_march_3_2012? case @answers[:utility_allowance] when Pays for Heating or # Cooling or receives MEAP or EUSP 394.0 when "Doesnt pay for heating or cooling but pays two other utilities" 239.0 when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" @answers[:actual_utility_cost] when "Pays telephone only" 40.0 else 0.0 end else 326 endenddef after_march_3_2012? Time.zone.now >= Time.new(2012, 3, 3)end
  64. 64. # deserted codedef standard_utility_allowance case @answers[:utility_allowance] when Pays for Heating or # Cooling or receives MEAP or EUSP 394.0# when "Doesnt pay for heating or cooling but pays two other utilities"# 239.0 when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" @answers[:actual_utility_cost] when "Pays telephone only" 40.0 else 0.0 endend
  65. 65. # deserted code# remove it. If it passes tests without the code, it is not needed.def standard_utility_allowance case @answers[:utility_allowance] when Pays for Heating or # Cooling or receives MEAP or EUSP 394.0 when "Doesnt pay for heating or cooling but pays one utility bill (NOT telephone)" @answers[:actual_utility_cost] when "Pays telephone only" 40.0 else 0.0 endend
  66. 66. A more complex example
  67. 67. # Stop clarifying code with comments;# Write code clearly instead.
  68. 68. # Questions? # References Therapeutic Refactoring, Katrina Owen http://confreaks.com/videos/1071-cascadiaruby2012-therapeutic-refactoring Chartjunk http://en.wikipedia.org/wiki/Chartjunk#cite_note-tufte-0 What Do Programmers Really Do Anyway? (aka Part 2 of the Yardstick saga), Peter Hallam http://blogs.msdn.com/b/peterhal/archive/2006/01/04/509302.aspx Clean Code, Robert Martin # My InfoNate Davis Olds #natedavisolds Benefits Data Trust lead developernate@davisolds.com ndavisolds@bdtrust.org www.bdtrust.org

×