Why you should document your code

Why you should
document you code!
Lennon Manchester
@leManchester
lennon.manchester@staunchrobots.com

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. "ofﬁcial
written instrument" any means, especially
graphic, proving the existence of a fact, the
accuracy or truth of a statement etc..

Loren Segal
@lsegal
http://yardoc.org/

Why nobody likes to
work with
Legacy CODE?

.... Ahh ok,
did I say does NOT
have
Documentation?

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 documentationcomprehensive documentation

...everyone pay
Attention!
When the class is good....

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 modiﬁed by many
programmers over 5 – 15 years and
they’ll all need to understand it.)
Communication

- Describe the behaviour (method or class).
ELEMENTS
of a
GOOD Doc

- Avoid the ﬁrst person ('We', 'I', 'You' is okay?!).
ELEMENTS
of a
GOOD Doc

- The ﬁrst sentence should summarize the method/class
ELEMENTS
of a
GOOD Doc

- Use note (@note) to say something the user
should know about it.
ELEMENTS
of a
GOOD Doc

- References (classes, methods, URLs, @see).
ELEMENTS
of a
GOOD Doc

- List of Parameters and expected returns types.
- References (classes, methods, URLs, @see).
ELEMENTS
of a
GOOD Doc

does not tell you
A viarablethe all history....name

def ﬁnd(name)
does not tell you

def ﬁnd(name)
String? “John”
does not tell you

def ﬁnd(name)
String? “John”
Symbol? :John
does not tell you

def ﬁnd(name)
String? “John”
Hash? { :ﬁrst => “John”, :last => “Lennon” }
Symbol? :John
does not tell you

ocumentation
riven
evelopment
D
D
D

Write Docs
for a Method
Write a
Method
Validate Code
with Docs

Write Docs
for a Method
Write a
Method
Validate Code
with Docs
Write Docs
for a Method
Write a
Method
Validate Code
with 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

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

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 ﬁlled into ﬁelds :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;

because is like
Bad Sex...
...still being better
than nothing....

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®

Lennon Manchester
lennon.manchester@staunchrobots.com
Thank You
Questions?
Lennon Manchester
@leManchester lennon.manchester@staunchrobots.com

Why you should document your code

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Why you should document your code

Ähnlich wie Why you should document your code (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Why you should document your code