Why you shoulddocument you code!

Lennon Manchester@leManchester lennon.manchester@staunchrobots.com

DOCUMENTATION

Let’s start since the beginning....

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

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

CRY!!!

Leonardo@shivamib

Loren Segal@lsegal

http://yardoc.org/

Legacy 2.0?

What is aLegacy?

Why nobody likes to work with

Legacy CODE?

Is it HARD?

Is it complex?

Is it complex?

Makes no sense?

CAOS?

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

haveDocumentation?

Agile

Methods

All inspired by the Agile values...

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

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

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

...everyone pay Attention!

When the class is good....

When the class is good....

README DRIVEN DEVELOPMENT

WriteME DRIVEN DEVELOPMENT

CRY!!!

Overhead of thoughts

Motivation

Hands On

Write it

It’s your guide

CODE DOCUMENTATION

Contract

Contract

Kent Beck

Kent Beck• Communication• Simplicity• Flexibility

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

ELEMENTS of a

GOOD Doc

- Describe the behaviour (method or class).

ELEMENTS of a

GOOD Doc

- Describe the behaviour (method or class).

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

ELEMENTS of a

GOOD Doc

- 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

- 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

- 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

- 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

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

def find(name)

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

def find(name)

String? “John”

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

def find(name)

String? “John”

Symbol? :John

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

def find(name)

String? “John”

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

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

ocumentation rivenevelopment

DDD

Write Docs for a Method

Write a Method

Validate Codewith Docs

Write Docs for a Method

Write a Method

Validate Codewith Docs

Write Docs for a Method

Write a Method

Validate Codewith Docs

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

Yardhttp://yardoc.org/

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

Hash?

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?

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

STOP

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

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

Why should you

document your code?

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

Does it make

sense?

because is like Bad Sex...

because is like Bad Sex...

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

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®

Lennon Manchesterlennon.manchester@staunchrobots.com

Thank You

Questions?

Lennon Manchester@leManchester lennon.manchester@staunchrobots.com