search

greenelab / library-access

Collecting data on whether library access to scholarly literature
Other
5 stars 3 forks source link

Reminder to add metadata to code files #14

Closed jglev closed 6 years ago

jglev commented 6 years ago

I'm opening this issue as a reminder that, per the Lab onboarding documentation checklist, we need to do the following at some point for code files:

  1. Sign the files
  2. Add a docstring to each of the files
  3. For smaller functions, add a docstring
dhimmel commented 6 years ago

Regarding "signing the files", we use the git history to take care of that. For example, see GitHub's blame for a file in this repo.

Regarding documentation, we do want to make things clearly documented. Usually, you want to write the doc as you make the files and functions. Sometimes code is clear and doesn't necessarily need docstrings. Are there specific areas of the code where documentation is lacking?

I think the main area where this repo is lacking documentation is in the README. We should update the README to better describe:

  1. what the repository does
  2. how to use, rerun, or modify it
  3. the repository contents (directories and files)

As a reference, you can look at greenelab/crossref to see how we might want to bolster the README.

dhimmel commented 6 years ago

@publicus sort of related to the above discussion, it would be good to add a note to the README letting users know how to rerun this analysis and to modify for another university.

jglev commented 6 years ago

@dhimmel Agreed! I can work on that, likely on Friday morning. Does that timing work for you?

dhimmel commented 6 years ago

Agreed! I can work on that, likely on Friday morning. Does that timing work for you?

Sure this is not a time sensitive change although it'd be nice to get it done.

dhimmel commented 6 years ago

Closed by https://github.com/greenelab/library-access/pull/26