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

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

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

Transcript

1. Андрей Twitter: AndrewRadev Github: AndrewRadev Blog: andrewradev.com
2. Vim
3. Vim
4. Документация
5. Аз <3 документация
6. READMEs
7. Wikis
8. Vim and :help
9. man
10. Понякога, аз !<3 документация
11. # Returns true def public? return true end
12. # Returns true def public? return false end
13. Проблемите • Документацията повтаря кода • Документацията не се поддържа
14. Самодокументиращ се код
15. def a return bb[1] end
16. # Returns the name # of the first day # of the week def a return bb[1] end
17. def first_day_of_week return day_names[MONDAY] end
18. Четим код > Документация
19. Legacy code
20. Четим код > Документация > Нечетим код
21. Математики разни
22. 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
23. # 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
24. Sprockets
25. Sprockets::Index
26. 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
27. 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.
28. (demo)
29. Имплементация • Repo • repo.url('lib/foo.rb') • tags • ctags_reader • Renderer • Ctags filename link → → • Ripper.lex • ObjectRegex
30. Добра идея? • Нова информация • Знания за домейна • Остарява?
31. Модули/класове, не функции
32. Лесна за поддръжка
33. Автомагическа документация!
34. @include rake-tasks (demo)
35. По-нататък: location, prerequisites
36. @include sinatra(...) (demo)
37. По-нататък: Ripper + ObjectRegex
38. Pretty graphs! (demo)
39. Имплементация • Regex-ове за връзките • Graphviz • Renderer • Base64-кодирана картинка
41. Автоматично или на ръка?
42. Лесна за четене?
43. Webpage
44. CLI > Webpage (demo)
45. Заслужава ли си?
46. Заслужава ли си? • Библиотеки • Open Source • 3-ма души на монолитен рейлс app • SOA, 10+ човека
47. Заслужава ли си tooling-а?
48. Навици
49. dawanda/doctools
50. Въпроси?