Documentar seu código é importante para facilitar a compreensão e manutenção do código por outros desenvolvedores no futuro. A documentação deve descrever o comportamento do código de forma clara e concisa, sem detalhes de implementação, e incluir parâmetros, retornos e referências. Boas práticas como Readme Driven Development envolvem escrever a documentação antes do código.

1. Por que você deveria
Documentar seu código?
Lennon Manchester
@leManchester

2. DOCUMENTAÇÃO

10. Vamos ao ínicio.....

12. Documentação?
É o conjunto de documentos...

13. Documentação?
É o conjunto de documentos...
Documento?
Um documento (do latim documentum derivado de docere “ensinar,
demonstrar”) é qualquer meio, sobretudo gráfico, que comprove a
existência de um fato, a exatidão ou a verdade de uma afirmação etc.
No meio jurídico, documentos são frequentemente sinônimos de atos,
cartas ou escritos que carregam um valor probatório.

19. choriiii
iiiiiiiiiiiii
iiiiii...

20. Leronardo?!?
@shivamib

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

22. Legado
2.0?

23. O que é um
Legado?

24. Porque ninguém gosta
de trabalhar com
Código Legado?

25. Difícil?

26. Complexo?

27. Coisas sem sentido?

28. CAOS?

29. .... Ahh tá,
Não tem
Documentação?

36. Métodos
Ágeis

41. Indivíduos e interação entre eles
mais que processos e ferramentas
Software em funcionamento e nunca mais
terar que documentar seu codigo
Colaboração com o cliente
mais que negociação de contratos
Responder a mudanças mais que seguir um plano

43. Então vamos para o
interessante....

44. README DRIVEN
DEVELOPMENT

45. WriteME DRIVEN
DEVELOPMENT

52. choriiii
iiiiiiiiiiiii
iiiiii...

53. Overhead de
pensamentos

54. Motivação

55. Mão na massa

56. Escreve

57. Seu guia

59. CODE DOCUMENTATION

60. Contrato

61. Contrato

70. Kent
Beck

71. Kent
Beck
• Communication
• Simplicity
• Flexibility

72. Communication
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.)

74. ELEMENTOS Boa Doc
de uma

75. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).

76. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).

77. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).
- A primeira linha deve ser um sumário do método/classe.

78. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).
- A primeira linha deve ser um sumário do método/classe.
- Deixe de fora detalhes de implementação a não ser que
eles afetem o seu uso.

79. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).
- A primeira linha deve ser um sumário do método/classe.
- Deixe de fora detalhes de implementação a não ser que
eles afetem o seu uso.
- Use notas (@note) para dizer algo para que seu
usuário deve saber.

80. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).
- A primeira linha deve ser um sumário do método/classe.
- Deixe de fora detalhes de implementação a não ser que
eles afetem o seu uso.
- Use notas (@note) para dizer algo para que seu
usuário deve saber.
- Referencias (classes, methods, URLs, @see).

81. ELEMENTOS Boa Doc de uma
- Descreva o comportamento (método ou classe).
- Evite a primeira pessoa ('We', 'I', 'You' is okay?!).
- A primeira linha deve ser um sumário do método/classe.
- Deixe de fora detalhes de implementação a não ser que
eles afetem o seu uso.
- Use notas (@note) para dizer algo para que seu
usuário deve saber.
- Referencias (classes, methods, URLs, @see).
- Lista de parametros e os seus retornos e tipos.

83. O Nome história inteira....
da variável
NÃO TE CONTA A

84. O Nome história inteira....
da variável
NÃO TE CONTA A
def find(name)

85. O Nome história inteira....
da variável
NÃO TE CONTA A
def find(name)
String? “John”

86. O Nome história inteira....
da variável
NÃO TE CONTA A
def find(name)
String? “John”
Symbol? :John

87. O Nome história inteira....
da variável
NÃO TE CONTA A
def find(name)
String? “John”
Symbol? :John
Hash? { :first => “John”, :last => “Lennon” }

88. D ocumentation
D riven
D evelopment

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

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

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

93. Yard http://yardoc.org/

94. Yard http://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

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

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

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

98. STOP

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

101. Por que você
deveria
Documentar
seu Código?

103. Does it make
sense?

104. References
Loren 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 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
Images collected from Google Images®

105. Obrigado
Perguntas?
Lennon Manchester
@leManchester