Por que você deveriaDocumentar seu código?Lennon Manchester@leManchester
DOCUMENTAÇÃO
Vamos ao ínicio.....
Documentação?É o conjunto de documentos...
Documentação?É o conjunto de documentos...Documento?Um documento (do latim documentum derivado de docere “ensinar,demonstr...
choriiiiiiiiiiiiiiiii iiiiii...
Leronardo?!?@shivamib
Loren Segal@lsegal http://yardoc.org/
Legado 2.0?
O que é um Legado?
Porque ninguém gosta de trabalhar com Código Legado?
Difícil?
Complexo?
Coisas sem sentido?
CAOS?
.... Ahh tá, Não temDocumentação?
Métodos Ágeis
Indivíduos e interação entre eles mais que processos e ferramentas Software em funcionamento e nunca mais te...
Então vamos para o interessante....
README DRIVEN DEVELOPMENT
WriteME DRIVENDEVELOPMENT
choriiiiiiiiiiiiiiiii iiiiii...
Overhead depensamentos
Motivação
Mão na massa
Escreve
Seu guia
CODE DOCUMENTATION
Contrato
Contrato
KentBeck
KentBeck• Communication• Simplicity• Flexibility
Communication Programs are read much more often than written and therefore should communicate clearly their intent. ...
ELEMENTOS Boa Doc de uma
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, ...
O Nome história inteira.... da variável NÃO TE CONTA A
O Nome história inteira.... da variável NÃO TE CONTA A def find(name)
O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John”
O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John” S...
O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John” ...
D ocumentationD rivenD evelopment
Write Docs Write a Validate Codefor a Method Method with Docs
Write Docs Write a Validate Codefor a Method Method with Docs Write a Write Docs Validate C...
class OS # Returns a list of String and # numbers displaying CPU information # of an OS: the CPU type, architecture, ve...
Yard http://yardoc.org/
Yard http://yardoc.org/class OS # @return [Array(String, String, String, Integer, Integer, Integer)] ...
class OS def processor_info { :cpu_type => cpu_type, :cpu_arch => cpu_arch, :cpu_vendor => cpu_vendor, ...
Hash?class OS def processor_info { :cpu_type => cpu_type, :cpu_arch => cpu_arch, :cpu_vendor => cpu_ven...
class OS # @return [Hash{Symbol=>[String, Integer]}] # processor info filled into fields :cpu_type, :cpu_arch, :cpu_vendor...
STOP
class ProcessorInfo # @return [String] CPU type (AMD, Intel, ...) attr_accessor :cpu_type # @return [String] CPU Archit...
Por que você deveria Documentarseu Código?
Does it make sense?
ReferencesLoren Segal - Just Say No To :nodoc: and Document Your Code!http://www.youtube.com/watch?v=tCw7CpRvYOEMaurício A...
Obrigado Perguntas? Lennon Manchester @leManchester
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
Por que voce deveria documentar seu codigo?
of 105

Por que voce deveria documentar seu codigo?

Slides from my internal talk at Locaweb
Published on: Mar 4, 2016
Published in: Technology      
Source: www.slideshare.net


Transcripts - Por que voce deveria documentar seu codigo?

  • 1. Por que você deveriaDocumentar seu código?Lennon Manchester@leManchester
  • 2. DOCUMENTAÇÃO
  • 3. Vamos ao ínicio.....
  • 4. Documentação?É o conjunto de documentos...
  • 5. Documentação?É o conjunto de documentos...Documento?Um documento (do latim documentum derivado de docere “ensinar,demonstrar”) é qualquer meio, sobretudo gráfico, que comprove aexistê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.
  • 6. choriiiiiiiiiiiiiiiii iiiiii...
  • 7. Leronardo?!?@shivamib
  • 8. Loren Segal@lsegal http://yardoc.org/
  • 9. Legado 2.0?
  • 10. O que é um Legado?
  • 11. Porque ninguém gosta de trabalhar com Código Legado?
  • 12. Difícil?
  • 13. Complexo?
  • 14. Coisas sem sentido?
  • 15. CAOS?
  • 16. .... Ahh tá, Não temDocumentação?
  • 17. Métodos Ágeis
  • 18. 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 contratosResponder a mudanças mais que seguir um plano
  • 19. Então vamos para o interessante....
  • 20. README DRIVEN DEVELOPMENT
  • 21. WriteME DRIVENDEVELOPMENT
  • 22. choriiiiiiiiiiiiiiiii iiiiii...
  • 23. Overhead depensamentos
  • 24. Motivação
  • 25. Mão na massa
  • 26. Escreve
  • 27. Seu guia
  • 28. CODE DOCUMENTATION
  • 29. Contrato
  • 30. Contrato
  • 31. KentBeck
  • 32. KentBeck• Communication• Simplicity• Flexibility
  • 33. 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.)
  • 34. ELEMENTOS Boa Doc de uma
  • 35. ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).
  • 36. ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, I, You is okay?!).
  • 37. 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.
  • 38. 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.
  • 39. 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 seuusuário deve saber.
  • 40. 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 seuusuário deve saber.- Referencias (classes, methods, URLs, @see).
  • 41. 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 seuusuário deve saber.- Referencias (classes, methods, URLs, @see).- Lista de parametros e os seus retornos e tipos.
  • 42. O Nome história inteira.... da variável NÃO TE CONTA A
  • 43. O Nome história inteira.... da variável NÃO TE CONTA A def find(name)
  • 44. O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John”
  • 45. O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John” Symbol? :John
  • 46. 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” }
  • 47. D ocumentationD rivenD evelopment
  • 48. Write Docs Write a Validate Codefor a Method Method with Docs
  • 49. Write Docs Write a Validate Codefor a Method Method with Docs Write a Write Docs Validate Code Method for a Method with Docs
  • 50. 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 ] endend
  • 51. Yard http://yardoc.org/
  • 52. 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 ] endend
  • 53. 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 } endend
  • 54. 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 } endend
  • 55. 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 } endend
  • 56. STOP
  • 57. 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_clockendclass 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 endend
  • 58. Por que você deveria Documentarseu Código?
  • 59. Does it make sense?
  • 60. ReferencesLoren Segal - Just Say No To :nodoc: and Document Your Code!http://www.youtube.com/watch?v=tCw7CpRvYOEMaurí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.htmlImages collected from Google Images®
  • 61. Obrigado Perguntas? Lennon Manchester @leManchester

Related Documents