0
# No comment.
# Stop clarifying code with comments;
# Stop clarifying code with comments;# Write code clearly instead.
# Clarifying comments are not                                         # documentation# Converts the object into textual ma...
# Clarifying comments are not                                          # documentation# Converts the object into textual m...
# Clarifying comments are not                                           # legal statements# Copyright (C) 2012 by Nate Dav...
# Clarifying comments are not                                   # reminder notes# FIXME high priority for nextdeploydef pr...
# Clarifying comments are not                                   # reminder notes# FIXME high priority for next     $ rake ...
# The attention of the comment                                                   # is outside the scope                   ...
# A clarifying comment’s attention is# directed internally # inserts a string between two other strings def process(str=’i...
# Clarifying comments are                                               # explanations                                    ...
# Clarifying comments are                                 # redundant                                 # of the code that f...
# Clarifying comments are                                             # apologizes                                        ...
# Clarifying comments are                                            # rants                                            # ...
# Clarifying comments are                                             # open letters                                      ...
# Clarifying comments are                                        # warnings                                        # of th...
# Clarifying comments are                                       # dialogs                                       # of the c...
# Clarifying comments are                      # inside jokes                      # of the code that follows.stop() # ham...
# Clarifying comments are                                        # misleading descriptions                                ...
# Clarifying comments are                                               # stashed codedef standard_utility_allowance      ...
# Clarifying comments are                                               # deserted code                                   ...
# Why should clarifying comments be removed?
# Why should clarifying comments be removed?# Clarifying comments are codejunk
# Why should clarifying comments be removed?# Clarifying comments are codejunk  term from Katrina Owen # talk entitled The...
# Why should clarifying comments be removed?# Clarifying comments are codejunk    term from Katrina Owen # talk entitled T...
Chartjunk refers to all visual elements in charts andgraphs that are not necessary to comprehend theinformation represente...
Codejunk refers to all visual elements in code thatare not necessary to comprehend the informationrepresented in the code,...
Understanding Code70%                                                                      New Code                       ...
# Why should clarifying comments be removed?
# Why should clarifying comments be removed?Because we spend most ofour time reading andunderstanding code
# Isn’t that why we write clarifying comments?
# Isn’t that why we write clarifying comments?No. We write clarifyingcomments because our codeisn’t clear enough.
The use of a clarifyingcomment admits the failureto write readable, clean code
The use of a clarifyingcomment admits the failureto write readable, clean code          # Stop clarifying code with commen...
# explanations
# explanations            # inserts a string between two other strings            def process(str=’inter’)             “us...
# explanations            # inserts a string between two other strings            def process(str=’inter’)             “us...
# redundant comment
# redundant comment        # inserts string        def insert_string(str=’inter’)         “use “ + str + ”polation”       ...
# redundant comment         # inserts string         def insert_string(str=’inter’)          “use “ + str + ”polation”    ...
# apologizing
# apologizing         # This code sucks! I know it. You know it.         # I am sorry that you have to read it.         de...
# apologizing          # This code sucks! I know it. You know it.          # I am sorry that you have to read it.         ...
# rants
# 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. PS...
# 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. PS...
# Open letters
# Open letters        #   Dear maintainer:        #        #   Once you are done trying to optimize this routine,        #...
# Open letters        #   Dear maintainer:        #        #   Once you are done trying to optimize this routine,        #...
# warnings
# warnings# After you run this code, take the day off.# It won’t finish until tomorrow.def im_compiling(stop_at=14.hours.fr...
# warnings# if it is meant to run long, warn at runtimedef im_compiling(stop_at=nil) if stop_at.nil?   print “This will ta...
# warnings# schedule optimization# OPTIMIZE: remove the n+1 database callsdef comment_summaries_for_everyone summaries = [...
# dialogs       # This is brilliant!       # Thanks. It’s nap time.
# dialogs       # This is brilliant!       # Thanks. It’s nap time.# email. chat. twitter. phone. how about talk?!?
# jokes
# jokes     stop() # hammertime
# jokes     stop() # hammertime# funny the first time, but does it need to be checked in? Delete it     stop()
# misleading descriptions
# misleading descriptions    # Returns the standard utility allowance    # based on how many utilities someone pays.    de...
# misleading descriptions    # Returns the standard utility allowance    # based on how many utilities someone pays.    de...
# stashed codedef standard_utility_allowance 324 # Uncomment this by March 3, 2012 when estimations switch back # # case @...
# stashed code# write it inline, set a note to clean it up# FIXME: After March 3, 2012def standard_utility_allowance if af...
# deserted codedef standard_utility_allowance case @answers[:utility_allowance] when Pays for Heating or # Cooling or rece...
# deserted code# remove it. If it passes tests without the code, it is not needed.def standard_utility_allowance case @ans...
A more complex example
# Stop clarifying code with comments;# Write code clearly instead.
# Questions?                                                                             # References                     ...
No comment
No comment
No comment
Upcoming SlideShare
Loading in...5
×

No comment

1,264

Published on

Stop clarifying code with comment; write code clearly instead.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
1,264
On Slideshare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
1
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • RDOC\n\n
  • YARD\n
  • \n
  • - When you become aware of something that needs to be done; just not now\n- Worse than clarifying code if there is no process to return to these problem areas.\n- Acknowledge a problem, stashes it for later fixing, and prevents sidetracks\n\n
  • In all of these examples, the attention of the comment is outside the scope of the accompanying source code; \n\nin contrast...\n\n\n
  • in contrast, clarifying comment’s attention is directed internally\n\nPOINTS TOWARD THE CODE\n\n\n
  • EXPLANATIONS\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • JOKES\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • I first heard this\n\n\n\n
  • I first heard this\n\n\n\n
  • I first heard this\n\n\n\n
  • I first heard this\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • Peter Hallam asserts that coders spend more time reading code than writing code; a lot more.\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • DESERTED CODE\n\n\n\n
  • EXPLANATIONS\n\n
  • EXPLANATIONS\n\n
  • EXPLANATIONS\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • dialogs\nmake sure they get it\n\n\n\n
  • JOKES\n\n\n\n
  • JOKES\n\n\n\n
  • JOKES\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • This makes sure that it works correctly on time and also scheduled to clean it up.\n\n\n\n
  • REDUNDANT\n\n\n\n
  • REDUNDANT\n\n\n\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Transcript of "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
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×