• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
No comment
 

No comment

on

  • 508 views

Stop clarifying code with comment; write code clearly instead.

Stop clarifying code with comment; write code clearly instead.

Statistics

Views

Total Views
508
Views on SlideShare
259
Embed Views
249

Actions

Likes
0
Downloads
0
Comments
0

3 Embeds 249

http://natedavisolds.com 213
http://localhost 31
http://www.natedavisolds.com 5

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • \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

No comment No comment Presentation Transcript

  • # 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 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
  • # 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
  • # 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.
  • # 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
  • # 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
  • # 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.
  • # A clarifying comment’s attention is# directed internally # inserts a string between two other strings def process(str=’inter’) “use “ + str + ”polation” end
  • # Clarifying comments are # explanations # of the code that follows.# inserts a string between two other stringsdef process(str=’inter’) “use “ + str + ”polation”end
  • # Clarifying comments are # redundant # of the code that follows.# inserts stringdef insert_string(str=’inter’) “use “ + str + ”polation”end
  • # 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
  • # 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.
  • # 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#
  • # 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
  • # 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
  • # Clarifying comments are # inside jokes # of the code that follows.stop() # hammertime
  • # 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
  • # 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
  • # 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
  • # 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 Therapeutic Refactoring on confreaks from Cascadia Ruby Conference
  • # 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.
  • 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.
  • 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.
  • Understanding Code70% New Code 5% Modifying Existing Code 25%# http://blogs.msdn.com/b/peterhal/archive/2006/01/04/509302.aspx Peter Hallam
  • # 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 comments; # Write code clearly instead.
  • # explanations
  • # explanations # inserts a string between two other strings def process(str=’inter’) “use “ + str + ”polation” end
  • # 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
  • # redundant comment
  • # redundant comment # inserts string def insert_string(str=’inter’) “use “ + str + ”polation” end
  • # redundant comment # inserts string def insert_string(str=’inter’) “use “ + str + ”polation” end# without comment def insert_string(str=’inter’) “use “ + str + ”polation” end
  • # apologizing
  • # 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
  • # 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
  • # 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. 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
  • # 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
  • # Open letters
  • # 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 #
  • # 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....
  • # warnings
  • # 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
  • # 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
  • # 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
  • # 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. def standard_utility_allowance 324 end
  • # 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
  • # 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
  • # 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
  • # 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
  • # 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
  • A more complex example
  • # Stop clarifying code with comments;# Write code clearly instead.
  • # 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