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

[Spencer Graves]

On 7/27/2014 7:46 AM, Luca Braglia wrote:
> On 27/07/14 -  09:33, Christophe Dutang wrote:
>> Hi Luca,
>>
>> Let me suggest to follow the table of contents of http://cran.r-project.org/doc/manuals/r-release/R-exts.html
>>
>> For example, you could use the following TOC:
>>
>> 1 - Creating R pkg
>> 2 - Writing documentation and vignettes
>> 3 - Profiling code
>> 4 - Debugging, spell checking
>> 5 - Foreign languages interfaces
>> 6 - GUI and other frond-ends
>> 7 - Unit testing
>> 8 - Benchmarking
>> 9 - Automation
>>
>>
>> Maybe 7 and 8 could be merged?
>>
>
> Thanks Christophe for the feedback
>
> 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 have a few doubts if "8.Linking GUIs and other front-ends to R"
> from R-exts could be strictly in topic with _R_package_
> development (eg looking at the list above) but not much
> experience in that area and jm2c.
>
> And I have to integrate these Gabor's suggestions yet :
>
> 1) List the software mentioned here or provide links:
>     http://en.wikibooks.org/wiki/R_Programming/Settings#Integrated_development_environment
>     http://en.wikipedia.org/wiki/Comparison_of_open-source_software_hosting_facilities
>     http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
>     http://en.wikipedia.org/wiki/Continuous_integration#Software
>
> 2) Go through the R Extensions manual and add all tools listed.
>
> 3) Use of Rcpp/Rcpp11 implies the use of C++ tools too and use of
>     rjava implies java tools.


       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.  That may 
sound crazy, but I had written code for decades and struggled 
continually with bugs introduced months or maybe years earlier.  "R CMD 
check" dramatically shortened the debug time to produce "trustworthy 
code" (John Chambers' "prime directive").  As a bonus, I got better 
software with documentation making it much easier to share with 
potential users -- in less time with less effort, heartache, blood, 
sweat and tears, etc.  I have not come to using roxygen2, though I've 
been enormously impressed with other things Hadley Wickham has done;  
fortune(298).


       This perspective is reflected in the Wikipedia article on 
"Package development process" and the comparison table of "Selected 
repositories" in the Wikipedia article on "Software repository".  I 
believe that both these articles could be improved by people with 
broader experience and deeper understanding of these issues than I have.


       Spencer Graves

> Further ideas/comments/proposals are welcome.
>
>
> Cheers, Luca
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel


-- 
Spencer Graves, PE, PhD
President and Chief Technology Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph:  408-655-4567
web:  www.structuremonitoring.com