If you write the *.Rd file before (like Spencer) or soon after writing the
code, then design errors will usually stick out at you, and you can modify
the functions. ?If you keep your functions small, you'll get them working
early, and won't have a lot of problems keeping them in sync with the docs,
because they won't change much once you get them right.
For me, the benefits are huge: ?I believe I tripled my software development
productivity almost overnight when I started writing documentation with
examples (unit tests) before writing the code. ?Then I run "R CMD check"
after every tiny change. ?This may seem like extra work, but it saves
debugging time, because any new problems are likely restricted to what I
changed. ?For example, I write a function A. ?Then I write B. ?Then I write
C. ?In the process of writing C, I change A. ?R CMD check after adding C
reveals that the change to A broke B. ?Without the R package discipline, it
could easily be a year before a found that a bug existed, and then it was an
enormous effort to find and fix it. ?(See Wikipedia, "Software repository",
"Package development process".) ?In addition to having better code is less
time for myself, I can easily share the results with others -- thereby
increasing my productivity substantially more than the factor of three I
mentioned.