On Fri, Apr 17, 2009 at 10:12 AM, Dirk Eddelbuettel <e...@debian.org> wrote: > > On 17 April 2009 at 09:05, Duncan Murdoch wrote: > | That would be a waste of time. People don't use the package > | documentation schemes that are in place; why would they use a new one? > > Because of scattered documentation and lack of best practices? Many things > are possible with R and packages, how many are really done consistently? I > think this points to a need for better examples, better docs, and better > package checking tools. > Best practices? Such things exist, and I am sure software engineering students are routinely introduced to them these days, but at the same time, I have seen projects where they were ignored and even where management told their engineers to not waste time documenting anything. :-( Of course I circumvented such direction by embedding my 'documentation' as comments within my code so that anyone who is assigned to maintain the code would know, from my comments and coding practices I both used and taught to my juniors there, how it all works. I remember some of my old FORTRAN code where there were more lines of comments documenting everything for other programmers than there were lines of code; all in one file so the programmers using the file would not have to look far to find the information they needed. Not as good as the now usual UML documentation, but better than nothing and essential in a project involving more than half a million lines of code.
No matter how good you get, there is always a need for more, and better, examples, documentation and tools. > I happended to have the same discussion via email last night with Brian > (CCed) who wanted to see NEWS / Changes in my CRANberries RSS feed for CRAN. > I suggested pretty much what Philippe suggested in the first post in this > thread --- with one addition. I think we need a test in R CMD check that > emits a warning if there is no inst/NEWS or inst/Changes or inst/Changelog. > This reminds me of a tool I encountered years ago (called aegis) that could be configured to not permit committing new code to production codebase unless there were unit tests for it, ideally an integration test or two, and that prior to commitment the entire build, including the new code, passed all existing tests for the project. A wonderful tool for ensuring new code didn't break things! But it works only is used as intended. After all, it would be trivial to write a dummy test that always passes regardless of what the application code really does. If you really want your developers to use some minimalist list of best practices, you really have to do two things. First you have to be able to demonstrate that they will make life easier for the developer. I never met a developer who would spend even a few minutes on a task for which they did not see a significant benefit. Even if you made it a condition of employment, you'd see on half hearted, sloppy efforts at tasks for which they see no significant benefit. Since time is so precious, an intermediate programmer is not likely to write usable documentation of his code for a junior developer that has to follow in his footsteps. Yes, as a condition of employment, he'll write something, but it will be terse, and next to useless for anyone who didn't write the code. Second, you have to make it relatively easy to do. No matter what the payoff for the developer, he won't do it if the only way he can get it done is to stand on his head eating peanuts and spitting the waste shells into a garbage container 5 meters away while typing with his toes, blindfolded. It isn't going to happen. And it can get worse in that I have seen software houses that provide services to develop custom software and they have a vested interest in making comprehension of their code so difficult that their clients have no option but to go back to them for maintainance and upgrades if they want it in a timely fashion. There are reasons why software developers don't use documentation frameworks that are available to them, and I have seen some larger software houses that have essentially capitulated to such human behaviour and hired documentation specialists. Who is best to develop documentation for a given product: the engineer who developed or an educator who has been assigned to teach people how to use it? I can both appreciate the original request and understand why people behave in a way that resulted in Duncan saying it is a waste of time because people don't use package documentation schemes that are available, and if I were managing a project I'd likely share his frustration with it. I certainly don't envy anyone trying to address this issue. Good luck. Ted ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
