why you should document your code
TRANSCRIPT
Why you shoulddocument you code!
Lennon Manchester@leManchester [email protected]
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®