search

UCL / rsd-engineeringcourse

Course materials for Research Software Engineering course.
http://github-pages.ucl.ac.uk/rsd-engineeringcourse/
Other
118 stars 101 forks source link

Writing Libraries page #94

Closed mattagape closed 5 years ago

mattagape commented 6 years ago

  1. It says "You can also maintain your library code in a Notebook, and use %%writefile to create your library." That sounds like a recipe for disaster to me, given what we know about the non-reproducibility of notebooks.

  2. To demonstrate good programming practice, the example code functions should have comments explaining what arguments they are expecting, and their types.

ageorgou commented 6 years ago

  1. Writing Python in text files:

    • Maybe we should mention this in one of the first lectures, and remove it from here (keeping the examples to generate the files, I guess, but pointint out that it's not great)
    • "Libraries are usually structured with multiple files, one for each class.": Not sure I agree with the one class per file statement, at least for Python
    • Maybe add an introductory sentence: "We will be turning the code we have written for the maze () into a library, so that other code can reuse it"

  2. Loading Our Package: The last paragraph mentions .pyc files, but there are none in the notebook output. We could change it to "If you see any files ending in .pyc, those are ..."

  3. The Python Path

    • Move the "Supplementary material" marker to the beginning of the section
    • We can change the multiple print statements to just print(sys.path[:-3] (and also update the path we're appending); as it is, it looks like something that was done interactively