Por que voce deveria documentar seu codigo?

396 views

Published on

Slides from my internal talk at Locaweb

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
396
On SlideShare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
1
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Bom a ideia surgiu numa conversa com o Leronardo, como o codigo esta crescendo mto rapido com o sys2, mta complexidade sendo aplicada nos projetos, pressão de tempo no desenvolvimento, sem !! Possivel Legado 2.0\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Por que voce deveria documentar seu codigo?

    1. 1. Por que você deveriaDocumentar seu código?Lennon Manchester@leManchester
    2. 2. DOCUMENTAÇÃO
    3. 3. Vamos ao ínicio.....
    4. 4. Documentação?É o conjunto de documentos...
    5. 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. 6. choriiiiiiiiiiiiiiiii iiiiii...
    7. 7. Leronardo?!?@shivamib
    8. 8. Loren Segal@lsegal http://yardoc.org/
    9. 9. Legado 2.0?
    10. 10. O que é um Legado?
    11. 11. Porque ninguém gosta de trabalhar com Código Legado?
    12. 12. Difícil?
    13. 13. Complexo?
    14. 14. Coisas sem sentido?
    15. 15. CAOS?
    16. 16. .... Ahh tá, Não temDocumentação?
    17. 17. Métodos Ágeis
    18. 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. 19. Então vamos para o interessante....
    20. 20. README DRIVEN DEVELOPMENT
    21. 21. WriteME DRIVENDEVELOPMENT
    22. 22. choriiiiiiiiiiiiiiiii iiiiii...
    23. 23. Overhead depensamentos
    24. 24. Motivação
    25. 25. Mão na massa
    26. 26. Escreve
    27. 27. Seu guia
    28. 28. CODE DOCUMENTATION
    29. 29. Contrato
    30. 30. Contrato
    31. 31. KentBeck
    32. 32. KentBeck• Communication• Simplicity• Flexibility
    33. 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. 34. ELEMENTOS Boa Doc de uma
    35. 35. ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).
    36. 36. ELEMENTOS Boa Doc de uma- Descreva o comportamento (método ou classe).- Evite a primeira pessoa (We, I, You is okay?!).
    37. 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. 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. 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. 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. 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. 42. O Nome história inteira.... da variável NÃO TE CONTA A
    43. 43. O Nome história inteira.... da variável NÃO TE CONTA A def find(name)
    44. 44. O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John”
    45. 45. O Nome história inteira.... da variável NÃO TE CONTA A def find(name) String? “John” Symbol? :John
    46. 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. 47. D ocumentationD rivenD evelopment
    48. 48. Write Docs Write a Validate Codefor a Method Method with Docs
    49. 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. 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. 51. Yard http://yardoc.org/
    52. 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. 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. 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. 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. 56. STOP
    57. 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. 58. Por que você deveria Documentarseu Código?
    59. 59. Does it make sense?
    60. 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. 61. Obrigado Perguntas? Lennon Manchester @leManchester

    ×