On 7/27/2014 9:23 AM, Luca Braglia wrote:
On 27/07/14 - 08:42, Spencer Graves wrote:
On 7/27/2014 7:46 AM, Luca Braglia wrote:
I'm starting to think I'd like to keep the "Source Code" section
separated from the "Documentation" section ... eg ideally the
macro topics could be in this order
1 - Creation
2 - Source Code
3 - Documentation
4 - Tools and services (was "Automation")
Furthermore IMHO a granular sub-topic structure is a plus (eg
few packages for a distinct/well-focused task is no problem,
maybe a resource ... )
An updated temp TOC (integrating your ideas, and some new
packages listed) could be
==============================================================
1 - Creation
o Creating R packages - utils::package.skeleton, pkgKitten,
Rcpp::Rcpp.package.skeleton
2 - Source code
o Foreign languages interfaces - base R support for that,
inline, Rcpp , Rcpp11, rJava
o Debugging - base::debug utils::recover and friends
o Code analysis - codetools
o Profiling - utils::Rprof, aprof, profr, proftools
o Benchmarking - base::system.time, microbenchmarking, rbenchmark
o Unit testing - RUnit, svUnit, testthat
3 - Documentation
o Writing Package Documentation (functions, data sets, classes
and methods, packages) - roxygen2
o Writing Vignettes - Sweave, knitr
o Spell checking - tools::aspell_package_* functions
4 - Tools and services
o Editors (supporting package development)
o IDEs (supporting package development)
o Makefiles
o Revision control (most common in the R community):
subversion, git
o Hosting services (most common in the R community):
r-forge, github
==============================================================
I've heard claims that people who write documentation with unit tests
first tend to get better code faster than people who write the code first
and documentation (and maybe examples and unit tests) later. I've heard
there is research behind this. However, I'm not sure where to find it.
Others may be able to suggest publications that support or refute this
claim.
In any event, I tend to create (a) documentation first, including (b)
unit tests in the examples section, before (c) writing code. When I started
writing R packages following this model, I felt my software development
productivity increased by a factor of 5 or so.
Hi Spencer,
I'm trying that way of developing too (test before code), but
the numbering in my previous mail are not meant to be suggestion
for development process/flow steps (apologies for that, it was
only a way to alternate lists (numbers for sections, bullets for
tasks), no numbering is really going to be included in the task
view).
The proposed TOC was compiled in a way that (to me) eases finding which
packages are available, given what are you working on (source code
or documentation) and the specific task you need to accomplish.
Of course: You need to write to match how your target audience
would most likely want to approach the subject.
Regarding "finding which packages are available", I didn't see
the sos package on the list: The "findFn" function searches the help
pages of contributed packages and returns the results sorted so the
package with the most matches and total score appear first.
"writeFindFn2xls" produces an Excel workbook with a package summary
followed by the list of individual pages. For me, it's the fastest
literature search I know for anything statistical. Whatever I find
there has documentation and working code that I can trace line by line
if I don't understand the documentation. I find things faster, and I
learn faster as a result. [Disclaimer: I'm the lead author of sos. If
anyone knows anything better, I'd like to know.]
Spencer
Best,
Luca
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
