Add Project structure and Writing code sections #59
Conversation
|
|
... and now it occurs to me that I should probably end the "Writing code" section with a reminder, or an exercise, to seek feedback on code that you're currently writing (i.e., code that isn't finished) ... |
|
Scientific Python provides helpful guides on a number of relevant topics, including some general design principles. Some of the topical guides are very detailed and, perhaps, a bit too much detail for our audience. |
|
We should share this PR with the CoP and ask them to provide suggestions, comments, etc, building on what we covered in yesterday's meeting. We can provide the live preview of the Project structure and Writing code sections. |
robmoss
force-pushed
the
section/project-structure
branch
from
004c1d2
to
c072a30
Compare
|
@EamonConway I've migrated this PR from mdBook to MkDocs As per my previous comment, we should consider sharing this PR with the CoP and ask them to provide suggestions, comments, etc. It probably covers some things that are relevant to the orientation guide. |
I started sketching out content for a project structure section, but this quickly branched out to include a variety of topics that are better described as writing code. These sections include several exercises. One uses my Australian 2020 COVID-19 forecasts repository as an example and asks the reader to think about how the README.md file could be improved.
robmoss
force-pushed
the
section/project-structure
branch
from
c072a30
to
9b1a720
Compare
|
I've rebased this so that it applies cleanly on the new site structure (Introduction / Orientation / Topical Guides / Community). |
|
Sorry git novice here so not sure if this is the right place to post this! As a suggestion for the Orientation section (which already looks super useful), it might be useful to have a few examples of code that are small and self-contained and do some simple task. For example, a function that reads in a long-form CSV data set and returns some aggregated values, e.g. number of occurrences of X on each day between Y and Z. This could serve as an exemplar for how to structure good code (comments, good variable naming, no magic numbers, well defined function inputs/outputs, etc.). It could also include an example of a test function, as I think the idea of automated tests may be a new concept for many (me included!). Ideally, keeping the tasks relatively simple will mean that code doesn't need to use too many language-specific features or packages but can illustrate principles in a language-agnostic way. Again apologies if this is in the wrong place, please feel free to tell me if I should post this somewhere else! |
|
Hi @michaelplanknz that's a great suggestion! Having examples that show rather than tell would be really useful. I've created a new issue #69 to act as a starting point, because it's not directly related to this pull request (absolutely no drama, and apologies for not having clearer instructions on the orientation guide page itself). |
|
@EamonConway can you please let me know if you're happy for me to merge this? |
|
@EamonConway mind you, I could probably cut down the cake analogy |
The previous version was far too long and detailed; the intent is to make a simple point, rather than tell a long story.
|
@EamonConway I've revised the cake analogy and added two more specific tips at the end. |
|
Hmm, the Coding Advice page could probably do with a few (very short) code examples too. |
|
@EamonConway I'm going to merge this in advance of our next CoP meeting, as we discussed yesterday. Thanks! |
I started sketching out content for a project structure section, but this quickly branched out to include a variety of topics that are better described as writing code.
Sources of motivation include:
I want to refer to real examples of public repositories (such as my 2020 COVID-19 forecasts one, which I mention in Project structure / Explain how it all works) and highlight what they do well and what they don't do well.