Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

20190809_KEW_comments #20

Open
9 of 20 tasks
wendtke opened this issue Aug 9, 2019 · 2 comments
Open
9 of 20 tasks

20190809_KEW_comments #20

wendtke opened this issue Aug 9, 2019 · 2 comments

Comments

@wendtke
Copy link

wendtke commented Aug 9, 2019

Feel free to incorporate or dismiss these suggestions. Let me know if clarification is needed on any points.

Meta

  • more explicit, real-life examples of why and when mod is useful
  • "inst/misc/example_module.R" could be an interesting, real-life example
  • remove empty author line in DESCRIPTION
  • clarify (in docs and code) the difference between mod::ule() and mod::module()

Food for thought

  • how might mod support psyphr? That might be a good approach to building a real-world example.

Language, description, and accessibility

  • split README into vignettes
  • fix typos and syntactical and grammatical errors (how would you like me to point those out?) (e.g., "declair" = a delicious declaration at breakfast)
  • delete unnecessary phrases in README and documentation (e.g., "This is a good question.")
  • reduce the use of semi-colons and use hyphens where appropriate
  • examples of approaches to modules in other languages
  • let users know they can use require() OR library() (don't find the crowd; guide its directions)
  • what does "spare qualification" mean?
  • double-check code style in vignettes (e.g., spacing, assignment conventions, etc.)
  • use complete sentences ("Another way is using provide() function to declair public variables, while all others become private" is missing a thing or two.)
  • don't assume your readers understand immediately (e.g., "The following demonstration should be self-explanatory..."
  • consider an alternative to "we feel"; you are the sole author, and feelings have nothing to do with this.
  • move terms and definitions to beginning of README, or consider a separate vignette with only terms and definitions at start of user experience

Code

  • showing my ignorance: Why do we have to quote a mod in drop() but not in use()? (e.g., drop("my_test_mod") vs. use(my_test_mod)
  • in the 'refer()' documentation or warnings (beyond default), it would be useful to let the user know that refer() will mask assignments from the previous module.
    e.g.,
my_other_test_mod <- mod::module({
refer(my_test_mod)
a <- 1
b <- 2
})
  • In regard to above comment, you might also consider an implementation tool that helps the user compare the contents of each module before a mask occurs. I am reminded of the option to compare versions within Microsoft. Would a function that compares the contents of two modules be feasible?
@iqis
Copy link
Owner

iqis commented Aug 9, 2019

Code

  • showing my ignorance: Why do we have to quote a mod in drop() but not in use()? (e.g., drop("my_test_mod") vs. use(my_test_mod)

    • Ideally both would take character strings. The user may supply bare symbol as argument, because use() attempts follow the convention set by require() and library(). The drop() function has no comparable counterparts, and thus follow the function it calls: detach()
  • in the 'refer()' documentation or warnings (beyond default), it would be useful to let the user know that refer() will mask assignments from the previous module.
    e.g.,

    • This is a good idea. The Tidyverse is sporting a verbose style to help the interactive user, too. I'll think about this and balance it with the R tradition of keeping mouth shut when nothing goes wrong.
my_other_test_mod <- mod::module({
refer(my_test_mod)
a <- 1
b <- 2
})
  • In regard to above comment, you might also consider an implementation tool that helps the user compare the contents of each module before a mask occurs. I am reminded of the option to compare versions within Microsoft. Would a function that compares the contents of two modules be feasible?
    • I think this would not be very necessary, as the user can simply do: ls(mod_b) %in% ls(mod_a) or something similar to get an idea for name conflict. The user is also expected to be familiar with the contents of either modules if he had created them.

@wendtke
Copy link
Author

wendtke commented Aug 9, 2019

  • showing my ignorance: Why do we have to quote a mod in drop() but not in use()? (e.g., drop("my_test_mod") vs. use(my_test_mod)

    • This is because use() attempts follow the convention set by require() and library().

Okay, that was my guess! Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants