[Rd] [Wishlist] a 'PackageDevelopment' Task View

[Spencer Graves]

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