Upload File

why you should document your code

120
Why you should document you code! Lennon Manchester @leManchester [email protected]

Upload: lennon-manchester

Post on 29-Jul-2015

678 views

Category:

Technology


0 download

Report

Tags:

TRANSCRIPT

Page 1: Why you should document your code

Why you shoulddocument you code!

Lennon Manchester@leManchester [email protected]

Page 2: Why you should document your code
Page 3: Why you should document your code

DOCUMENTATION

Page 4: Why you should document your code
Page 5: Why you should document your code
Page 6: Why you should document your code
Page 7: Why you should document your code
Page 8: Why you should document your code
Page 9: Why you should document your code
Page 10: Why you should document your code
Page 11: Why you should document your code

Let’s start since the beginning....

Page 12: Why you should document your code
Page 13: Why you should document your code

Documentation? Documentation a set of documents provided on paper, or online, or on digital or analog media

Page 14: Why you should document your code

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..

Page 15: Why you should document your code
Page 16: Why you should document your code
Page 17: Why you should document your code
Page 18: Why you should document your code
Page 19: Why you should document your code
Page 20: Why you should document your code
Page 21: Why you should document your code
Page 22: Why you should document your code
Page 23: Why you should document your code
Page 24: Why you should document your code

CRY!!!

Page 25: Why you should document your code

Leonardo@shivamib

Page 26: Why you should document your code

Loren Segal@lsegal

http://yardoc.org/

Page 27: Why you should document your code

Legacy 2.0?

Page 28: Why you should document your code

What is aLegacy?

Page 29: Why you should document your code

Why nobody likes to work with

Legacy CODE?

Page 30: Why you should document your code

Is it HARD?

Page 31: Why you should document your code

Is it complex?

Page 32: Why you should document your code

Is it complex?

Page 33: Why you should document your code

Makes no sense?

Page 34: Why you should document your code

CAOS?

Page 35: Why you should document your code

.... Ahh ok, did I say does NOT

haveDocumentation?

Page 36: Why you should document your code
Page 37: Why you should document your code
Page 38: Why you should document your code
Page 39: Why you should document your code
Page 40: Why you should document your code
Page 41: Why you should document your code
Page 42: Why you should document your code

Agile

Methods

Page 43: Why you should document your code
Page 44: Why you should document your code
Page 45: Why you should document your code
Page 46: Why you should document your code
Page 47: Why you should document your code
Page 48: Why you should document your code

All inspired by the Agile values...

Page 49: Why you should document your code

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

Page 50: Why you should document your code

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

Page 51: Why you should document your code

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

Page 52: Why you should document your code

...everyone pay Attention!

When the class is good....

Page 53: Why you should document your code

When the class is good....

Page 54: Why you should document your code

README DRIVEN DEVELOPMENT

Page 55: Why you should document your code

WriteME DRIVEN DEVELOPMENT

Page 56: Why you should document your code
Page 57: Why you should document your code
Page 58: Why you should document your code
Page 59: Why you should document your code
Page 60: Why you should document your code
Page 61: Why you should document your code
Page 62: Why you should document your code
Page 63: Why you should document your code

CRY!!!

Page 64: Why you should document your code

Overhead of thoughts

Page 65: Why you should document your code

Motivation

Page 66: Why you should document your code

Hands On

Page 67: Why you should document your code

Write it

Page 68: Why you should document your code

It’s your guide

Page 69: Why you should document your code
Page 70: Why you should document your code

CODE DOCUMENTATION

Page 71: Why you should document your code

Contract

Page 72: Why you should document your code

Contract

Page 73: Why you should document your code
Page 74: Why you should document your code
Page 75: Why you should document your code
Page 76: Why you should document your code
Page 77: Why you should document your code
Page 78: Why you should document your code
Page 79: Why you should document your code
Page 80: Why you should document your code
Page 81: Why you should document your code

Kent Beck

Page 82: Why you should document your code

Kent Beck• Communication• Simplicity• Flexibility

Page 83: Why you should document your code

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

Page 84: Why you should document your code
Page 85: Why you should document your code

ELEMENTS of a

GOOD Doc

Page 86: Why you should document your code

- Describe the behaviour (method or class).

ELEMENTS of a

GOOD Doc

Page 87: Why you should document your code

- Describe the behaviour (method or class).

- Avoid the first person ('We', 'I', 'You' is okay?!).

ELEMENTS of a

GOOD Doc

Page 88: Why you should document your code

- 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

Page 89: Why you should document your code

- 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

Page 90: Why you should document your code

- 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

Page 91: Why you should document your code

- 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

Page 92: Why you should document your code
Page 93: Why you should document your code

does not tell youA viarable the all history....name

Page 94: Why you should document your code

def find(name)

does not tell youA viarable the all history....name

Page 95: Why you should document your code

def find(name)

String? “John”

does not tell youA viarable the all history....name

Page 96: Why you should document your code

def find(name)

String? “John”

Symbol? :John

does not tell youA viarable the all history....name

Page 97: Why you should document your code

def find(name)

String? “John”

Hash? { :first => “John”, :last => “Lennon” }Symbol? :John

does not tell youA viarable the all history....name

Page 98: Why you should document your code

ocumentation rivenevelopment

DDD

Page 99: Why you should document your code

Write Docs for a Method

Write a Method

Validate Codewith Docs

Page 100: Why you should document your code

Write Docs for a Method

Write a Method

Validate Codewith Docs

Write Docs for a Method

Write a Method

Validate Codewith Docs

Page 101: Why you should document your code
Page 102: Why you should document your code

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

Page 103: Why you should document your code

Yardhttp://yardoc.org/

Page 104: Why you should document your code
Page 105: Why you should document your code

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

Page 106: Why you should document your code
Page 107: Why you should document your code

Hash?

Page 108: Why you should document your code

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?

Page 109: Why you should document your code

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

Page 110: Why you should document your code

STOP

Page 111: Why you should document your code
Page 112: Why you should document your code

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

Page 113: Why you should document your code

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

Page 114: Why you should document your code

Why should you

document your code?

Page 115: Why you should document your code

- Contribute with your code; - Improve your experience;- Think about you and the next;

Page 116: Why you should document your code

Does it make

sense?

Page 117: Why you should document your code

because is like Bad Sex...

Page 118: Why you should document your code

because is like Bad Sex...

...still being better than nothing....

Page 119: Why you should document your code

ReferencesLoren Segal - Just Say No To :nodoc: and Document Your 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 Beckhttp://blog.iterate.no/2012/06/20/programming-like-kent-beck/

Tom Preston-Wernerhttp://tom.preston-werner.com/2010/08/23/readme-driven-development.html

Jef RaskinComments are More Important than Code

Images collected from Google Images®

Page 120: Why you should document your code

Lennon [email protected]

Thank You

Questions?

Lennon Manchester@leManchester [email protected]


Why You Should

Why the Commercial Code Should be 'Uniform

Why Should I Evangelize?

Why should we worship?

SHOULD LOOK AT WEBCON · 2 Why a Brand ” Workflow ser Should Look at WEBCON We at WEBCON get asked – a lot – how we compare to various low-code/no-code application tools and

Why you should

The Da Vinci Code Why Should Christians Care, Critique, and Converse?

Why women should code

ISLAM Part 1. So, why should we care about Islam? Why should we study about it? So, why should we care about Islam? Why should we study about it?

Why should libraries become publishers? And why should you care?, Simon Bains

Why Designers Should Code

Should designers code?

Why Designers Should Learn How To Code

Why Spiritual People should be talking about the DaVinci Code

The Why Code

Why you should exhibit! Why you should exhibit! 2019 Flyer.pdf · Why you should exhibit! Why you should exhibit! C-star: the most professional retail trade show in shop design and

Why Should We

Why Should We Rejoice?

Why women should lift

Why Every Startup Employee Should Learn To Code

5 Reasons why designers should code by LAVA Brands

Why should marketers learn code and why should software developers understand marketing?

Top 10 Reasons toNotShare Your Code (and why …faculty.washington.edu/rjl/talks/LeVeque_CSE2011.pdfTop 10 Reasons toNotShare Your Code (and why you should anyway) Randall J. LeVeque

What The Fuzz! Or Why You Should Really Fuzz Your RTC Code · 2020. 7. 31. · What The Fuzz! Or Why You Should Really Fuzz Your RTC Code Lorenzo Miniero @elminiero Kamailio World

JEAA Presentation - Why Should Communicators Learn to Code?

Why We Should Give Generously Give money generously Why We Should Give Generously

Why should i_archive

Why should your child "should" attend preschool

10 Reasons Why You Should Outsource Your Code Development

BY: TIM BIGGIN Static Code Analysis. Overview What Static Code Analysis Does Why Should You Use It? How is it Used? Types of Static Code Analysis Benefits

Why Should I Believe The Bible is God’s Book? Why Should I Believe That I Need God? Why Should I Believe That I Can Trust In God? Why Should I Become a

Responsive Web Design Webinar - Charity Dynamics · What is Responsive Design? One URL One Content Set One code Set Multiple Devices . 10 Why Should We Care? ... Why Should We Care?

Why Business Should Support Early Childhood Educationfoundationcenter.org/grantmaker/gustafson/docs/Why-Business-Should... · Why Business Should Support Early Childhood Education

Why Should Advertiser Should Use VOGUE

Why you should