Why you should document your code

827 views

Published on

Slides from my speech that I did internally at Locaweb and now in a German Conf supported by Infopark.
http://www.infopark.com/en/events/cloud-developer-camp/munich

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
827
On SlideShare
0
From Embeds
0
Number of Embeds
183
Actions
Shares
0
Downloads
5
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Why you should document your code

  1. 1. Why you should document you code! Lennon Manchester @leManchester lennon.manchester@staunchrobots.com
  2. 2. DOCUMENTATION
  3. 3. Let’s start since the beginning....
  4. 4. Documentation? Documentation a set of documents provided on paper, or online, or on digital or analog media
  5. 5. Documentation? Documentation a set of documents provided on paper, or online, or on digital or analog media Document? Document from Latin documentum "example, proof, lesson," in M.L. "official written instrument" any means, especially graphic, proving the existence of a fact, the accuracy or truth of a statement etc..
  6. 6. CRY!!!
  7. 7. Leonardo @shivamib
  8. 8. Loren Segal @lsegal http://yardoc.org/
  9. 9. Legacy 2.0?
  10. 10. What is a Legacy?
  11. 11. Why nobody likes to work with Legacy CODE?
  12. 12. Is it HARD?
  13. 13. Is it complex?
  14. 14. Is it complex?
  15. 15. Makes no sense?
  16. 16. CAOS?
  17. 17. .... Ahh ok, did I say does NOT have Documentation?
  18. 18. Agile Methods
  19. 19. All inspired by the Agile values...
  20. 20. Responding to change over following a plan Individuals and interactions over processes and tools Working software over Customer collaboration over contract negotiation write any kind of documentation
  21. 21. Responding to change over following a plan Individuals and interactions over processes and tools Working software over Customer collaboration over contract negotiation write any kind of documentation
  22. 22. Responding to change over following a plan Individuals and interactions over processes and tools Working software over Customer collaboration over contract negotiation write any kind of documentationcomprehensive documentation
  23. 23. ...everyone pay Attention! When the class is good....
  24. 24. When the class is good....
  25. 25. README DRIVEN DEVELOPMENT
  26. 26. WriteME DRIVEN DEVELOPMENT
  27. 27. CRY!!!
  28. 28. Overhead of thoughts
  29. 29. Motivation
  30. 30. Hands On
  31. 31. Write it
  32. 32. It s your guide
  33. 33. CODE DOCUMENTATION
  34. 34. Contract
  35. 35. Contract
  36. 36. Kent Beck
  37. 37. Kent Beck • Communication • Simplicity • Flexibility
  38. 38. Programs are read much more often than written and therefore should communicate clearly their intent. Code is primarily means of communication. (For a typical enterprise system, a lot of code will be modified by many programmers over 5 – 15 years and they’ll all need to understand it.) Communication
  39. 39. ELEMENTS of a GOOD Doc
  40. 40. - Describe the behaviour (method or class). ELEMENTS of a GOOD Doc
  41. 41. - Describe the behaviour (method or class). - Avoid the first person ('We', 'I', 'You' is okay?!). ELEMENTS of a GOOD Doc
  42. 42. - Describe the behaviour (method or class). - Avoid the first person ('We', 'I', 'You' is okay?!). - The first sentence should summarize the method/class ELEMENTS of a GOOD Doc
  43. 43. - Describe the behaviour (method or class). - Avoid the first person ('We', 'I', 'You' is okay?!). - The first sentence should summarize the method/class - Use note (@note) to say something the user should know about it. ELEMENTS of a GOOD Doc
  44. 44. - Describe the behaviour (method or class). - Avoid the first person ('We', 'I', 'You' is okay?!). - The first sentence should summarize the method/class - Use note (@note) to say something the user should know about it. - References (classes, methods, URLs, @see). ELEMENTS of a GOOD Doc
  45. 45. - List of Parameters and expected returns types. - Describe the behaviour (method or class). - Avoid the first person ('We', 'I', 'You' is okay?!). - The first sentence should summarize the method/class - Use note (@note) to say something the user should know about it. - References (classes, methods, URLs, @see). ELEMENTS of a GOOD Doc
  46. 46. does not tell you A viarablethe all history....name
  47. 47. def find(name) does not tell you A viarablethe all history....name
  48. 48. def find(name) String? “John” does not tell you A viarablethe all history....name
  49. 49. def find(name) String? “John” Symbol? :John does not tell you A viarablethe all history....name
  50. 50. def find(name) String? “John” Hash? { :first => “John”, :last => “Lennon” } Symbol? :John does not tell you A viarablethe all history....name
  51. 51. ocumentation riven evelopment D D D
  52. 52. Write Docs for a Method Write a Method Validate Code with Docs
  53. 53. Write Docs for a Method Write a Method Validate Code with Docs Write Docs for a Method Write a Method Validate Code with Docs
  54. 54. class OS # Returns a list of String and # numbers displaying CPU information # of an OS: the CPU type, architecture, vendor # clock speed (as integer), temperature (as # integer) and voltage (as integer) def processor_info [ cpu_type, cpu_arch, cpu_vendor, cpu_clock, cpu_temp, cpu_voltage ] end end
  55. 55. Yardhttp://yardoc.org/
  56. 56. class OS # @return [Array(String, String, String, Integer, Integer, Integer)] # CPU type, architecture, vendor, clock speed, temp and voltage of an OS def processor_info [ cpu_type, cpu_arch, cpu_vendor, cpu_clock, cpu_temp, cpu_voltage ] end end
  57. 57. Hash?
  58. 58. class OS def processor_info { :cpu_type => cpu_type, :cpu_arch => cpu_arch, :cpu_vendor => cpu_vendor, :cpu_clock => cpu_clock, :cpu_temp => cpu_temp, :cpu_voltage => cpu_voltage } end end Hash?
  59. 59. class OS # @return [Hash{Symbol=>[String, Integer]}] # processor info filled into fields :cpu_type, :cpu_arch, :cpu_vendor, # :cpu_clock (Integer), :cpu_temp (Integer), :cpu_voltage (Integer) # representing proc values of a CPU def processor_info { :cpu_type => cpu_type, :cpu_arch => cpu_arch, :cpu_vendor => cpu_vendor, :cpu_clock => cpu_clock, :cpu_temp => cpu_temp, :cpu_voltage => cpu_voltage } end end
  60. 60. STOP
  61. 61. class OS # @return [Hash{Symbol=>[String, Integer]}] # processor info filled into fields :cpu_type, :cpu_arch, :cpu_vendor, # :cpu_clock (Integer), :cpu_temp (Integer), :cpu_voltage (Integer) # representing proc values of a CPU def processor_info { :cpu_type => cpu_type, :cpu_arch => cpu_arch, :cpu_vendor => cpu_vendor, :cpu_clock => cpu_clock, :cpu_temp => cpu_temp, :cpu_voltage => cpu_voltage } end end
  62. 62. class ProcessorInfo # @return [String] CPU type (AMD, Intel, ...) attr_accessor :cpu_type # @return [String] CPU Architeture (x86,ARM) attr_accessor :cpu_arch # @return [String] CPU speed in hz (3.4.ghz = 3400) attr_accessor :cpu_clock end class OS # @return [ProcessorInfo] proc info of current OS def processor_info ProcessorInfo.new.tap do |p| p.cpu_type, p.cpu_arch, p.cpu_ clock = cpu_type, cpu_arch, cpu_clock end end end
  63. 63. Why should you document your code?
  64. 64. - Contribute with your code; - Improve your experience; - Think about you and the next;
  65. 65. Does it make sense?
  66. 66. because is like Bad Sex...
  67. 67. because is like Bad Sex... ...still being better than nothing....
  68. 68. References Loren Segal - Just Say No To :nodoc: and DocumentYour Code! http://www.youtube.com/watch?v=tCw7CpRvYOE Maurício Aniche at QCon SP (2012): Métodos ágeis: o que é folclore e o que é real? Krzysztof, Stig, and Jakub - Programming like Kent Beck http://blog.iterate.no/2012/06/20/programming-like-kent-beck/ Tom Preston-Werner http://tom.preston-werner.com/2010/08/23/readme-driven-development.html Jef Raskin Comments are More Important than Code Images collected from Google Images®
  69. 69. Lennon Manchester lennon.manchester@staunchrobots.com Thank You Questions? Lennon Manchester @leManchester lennon.manchester@staunchrobots.com

×