Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Документация (RogueConf 2013)

Документация (RogueConf 2013)

Лекция, в която представям възгледите си за писането на документация и няколко мои експериментални tool-чета за улесняване на процеса по документиране на код.

Видео: http://youtu.be/0aZ0LRxuq_I

Andrew Radev

March 30, 2013
Tweet

More Decks by Andrew Radev

Other Decks in Programming

Transcript

  1. Андрей
    Twitter: AndrewRadev
    Github: AndrewRadev
    Blog: andrewradev.com

    View full-size slide

  2. Документация

    View full-size slide

  3. Аз <3 документация

    View full-size slide

  4. Vim and :help

    View full-size slide

  5. Понякога,
    аз !<3 документация

    View full-size slide

  6. # Returns true
    def public?
    return true
    end

    View full-size slide

  7. # Returns true
    def public?
    return false
    end

    View full-size slide

  8. Проблемите

    Документацията повтаря кода

    Документацията не се поддържа

    View full-size slide

  9. Самодокументиращ се код

    View full-size slide

  10. def a
    return bb[1]
    end

    View full-size slide

  11. # Returns the name
    # of the first day
    # of the week
    def a
    return bb[1]
    end

    View full-size slide

  12. def first_day_of_week
    return day_names[MONDAY]
    end

    View full-size slide

  13. Четим код > Документация

    View full-size slide

  14. Четим код > Документация
    > Нечетим код

    View full-size slide

  15. Математики разни

    View full-size slide

  16. class RungeKutta
    attr_reader :h
    def initialize(h, f)
    @f = f
    @h = h.to_f
    end
    def call(x, y)
    k1 = h * f(x, y)
    k2 = h * f(x + h/2, y + k1/2)
    k3 = h * f(x + h, y - k1 + 2*k2)
    y + (1.0/6.0) * (k1 + 4*k2 + k3)
    end
    def f(*args)
    @f.call(*args)
    end
    end

    View full-size slide

  17. # Implements a third-order Runge-Kutta algorithm
    # for finding the solution to an ODE.
    #
    # See http://en.wikipedia.org/wiki/Runge_kutta
    class RungeKutta
    # ...
    end

    View full-size slide

  18. Sprockets::Index

    View full-size slide

  19. module Sprockets
    # `Index` is a special cached version of
    # `Environment`.
    #
    # The expection is that all of its file system
    # methods are cached for the instances lifetime.
    # This makes `Index` much faster. This behavior
    # is ideal in production environments where the
    # file system is immutable.
    #
    # `Index` should not be initialized directly.
    # Instead use `Environment#index`.
    class Index < Base
    # ...
    end
    end

    View full-size slide

  20. The basic thing you need to get asset
    compilation working is an instance of
    `Environment`. That class implements the rack
    interface, so you could simply `run
    Sprockets::Environment.new` and get a rack
    server up that serves assets. For production use,
    you can use the `index` method to get an `Index`
    object, which is read-only and therefore faster.

    View full-size slide

  21. Имплементация

    Repo

    repo.url('lib/foo.rb')

    tags

    ctags_reader

    Renderer

    Ctags filename link
    → →

    Ripper.lex

    ObjectRegex

    View full-size slide

  22. Добра идея?

    Нова информация

    Знания за домейна

    Остарява?

    View full-size slide

  23. Модули/класове, не
    функции

    View full-size slide

  24. Лесна за поддръжка

    View full-size slide

  25. Автомагическа
    документация!

    View full-size slide

  26. @include rake-tasks
    (demo)

    View full-size slide

  27. По-нататък:
    location, prerequisites

    View full-size slide

  28. @include sinatra(...)
    (demo)

    View full-size slide

  29. По-нататък:
    Ripper + ObjectRegex

    View full-size slide

  30. Pretty graphs!
    (demo)

    View full-size slide

  31. Имплементация

    Regex-ове за връзките

    Graphviz

    Renderer

    Base64-кодирана картинка

    View full-size slide

  32. Автоматично
    или
    на ръка?

    View full-size slide

  33. Лесна за четене?

    View full-size slide

  34. CLI > Webpage
    (demo)

    View full-size slide

  35. Заслужава ли си?

    View full-size slide

  36. Заслужава ли си?

    Библиотеки

    Open Source

    3-ма души на монолитен рейлс app

    SOA, 10+ човека

    View full-size slide

  37. Заслужава ли си tooling-а?

    View full-size slide

  38. Навици

    View full-size slide

  39. dawanda/doctools

    View full-size slide

  40. Въпроси?

    View full-size slide