From 97c4151ae7132fbded6b9a601b664f56c12723ad Mon Sep 17 00:00:00 2001 From: MarionBWeinzierl Date: Thu, 4 Jul 2024 16:04:32 +0100 Subject: [PATCH 1/3] removed some slides and implemented other changes from dry run --- slides/_comments_docstrings.qmd | 82 ------------------------------- slides/_fstrings_magic_config.qmd | 9 +++- slides/_licenses.qmd | 3 +- slides/python.qmd | 19 ++++--- 4 files changed, 18 insertions(+), 95 deletions(-) diff --git a/slides/_comments_docstrings.qmd b/slides/_comments_docstrings.qmd index bbece53..ea6ee9f 100644 --- a/slides/_comments_docstrings.qmd +++ b/slides/_comments_docstrings.qmd @@ -51,8 +51,6 @@ Cat code comment image by [35_equal_W](https://www.reddit.com/r/ProgrammerHumor/ ## Comments - some thoughts^[Adapted from [@stackoverflow_comments]] {.smaller} -::: {.incremental} - - Comments should not duplicate the code. - Good comments do not excuse unclear code. - Comments should dispel confusion, not cause it. @@ -65,8 +63,6 @@ Cat code comment image by [35_equal_W](https://www.reddit.com/r/ProgrammerHumor/ - Comments are not documentation. - Read by developers, documentation is for... -::: - ## Docstrings {.smaller} @@ -180,84 +176,6 @@ def calculate_gyroradius(mass, v_perp, charge, B, gamma=None): :::: -## Docstrings - pydocstyle {.smaller} - -:::: {.columns} - -::: {.column width="50%"} -[pydocstyle](https://www.pydocstyle.org/en/stable/) is a tool we can use to help -ensure the quality of our docstrings.[^2] - -:::{ style="font-size: 75%;"} - -```bash -(myvenv) $ pip install pydocstyle -(myvenv) $ pydocstyle myfile.py -(myvenv) $ pydocstyle mydirectory/ -(myvenv) $ -(myvenv) $ -(myvenv) $ pydocstyle gyroradius.py -gyroradius.py:2 in public function `calculate_gyroradius`: - D202: No blank lines allowed after function docstring (found 1) -gyroradius.py:2 in public function `calculate_gyroradius`: - D400: First line should end with a period (not 'd') -gyroradius.py:2 in public function `calculate_gyroradius`: - D401: First line should be in imperative mood (perhaps 'Calculate', not 'Calculates') -(myvenv) $ -``` -::: - -Note: pydocstyle does not catch missing variables in docstrings. -This can be done with [Pylint's docparams and docstyle extensions](https://pylint.pycqa.org/en/latest/user_guide/checkers/extensions.html) -but is left as an exercise to the reader. -::: -::: {.column} -:::{ style="font-size: 75%;"} -```python -def calculate_gyroradius(mass, v_perp, charge, B, gamma=None): - """ - Calculates the gyroradius of a charged particle in a magnetic field - - Parameters - ---------- - mass : float - The mass of the particle [kg] - v_perp : float - velocity perpendicular to magnetic field [m/s] - charge : float - particle charge [coulombs] - B : float - Magnetic field strength [teslas] - gamma : float, optional - Lorentz factor for relativistic case. default=None for non-relativistic case. - - Returns - ------- - r_g : float - Gyroradius of particle [m] - - Notes - ----- - .. [1] Walt, M, "Introduction to Geomagnetically Trapped Radiation," - Cambridge Atmospheric and Space Science Series, equation (2.4), 2005. - """ - - r_g = mass * v_perp / (abs(charge) * B) - - if gamma: - r_g = r_g * gamma - - return r_g -``` -::: -::: -:::: - - -[^2]: Note that pydocstyle is [deprecated](https://github.com/PyCQA/pydocstyle/pull/658) as of the end of 2023. Longer-term look out for a replacement (likely Ruff or Pylint extension). - - - ## Exercise 5 {.smaller} Go to exercise 5 and examine the comments: diff --git a/slides/_fstrings_magic_config.qmd b/slides/_fstrings_magic_config.qmd index 1dbe3b8..6b8bdec 100644 --- a/slides/_fstrings_magic_config.qmd +++ b/slides/_fstrings_magic_config.qmd @@ -1,5 +1,6 @@ # Writing better (Python) code + ## Remove Magic Numbers {.smaller} @@ -198,7 +199,7 @@ Magic Numbers - Look through the code and identify any magic numbers. - Implement what you feel is the best approach in each case - + + Configuration settings - There is helpfully a list of configurable inputs at the end of the file under `"__main__"`.\ We can improve on this, however, by placing them in a configuration file. - Create an appropriate json file to be read in as a dictionary and passed to the main function. + ::: :::: + diff --git a/slides/_licenses.qmd b/slides/_licenses.qmd index d1fc922..ba68799 100644 --- a/slides/_licenses.qmd +++ b/slides/_licenses.qmd @@ -37,6 +37,7 @@ The above copyright notice and this permission notice shall be included in all c THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` + diff --git a/slides/python.qmd b/slides/python.qmd index 242bafc..d16faaa 100644 --- a/slides/python.qmd +++ b/slides/python.qmd @@ -130,8 +130,7 @@ Beyond the scope of today are a few other honourable mentions: - Adding type hinting to python code - how and why? - Type checking with mypy -These lessons will be added to the course content in future but are beyond the scope -of today. +These lessons are beyond the scope of today. ## Exercise 5 {.smaller} Go to exercise 5 and examine the comments: From 7422beab7c0625655df0a388f37a218840200fe9 Mon Sep 17 00:00:00 2001 From: MarionBWeinzierl Date: Thu, 4 Jul 2024 17:02:14 +0100 Subject: [PATCH 3/3] also remove config file part --- slides/_fstrings_magic_config.qmd | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/slides/_fstrings_magic_config.qmd b/slides/_fstrings_magic_config.qmd index 6b8bdec..8ba3b60 100644 --- a/slides/_fstrings_magic_config.qmd +++ b/slides/_fstrings_magic_config.qmd @@ -134,7 +134,7 @@ def bpm(l): ::: :::: - + @@ -208,14 +208,13 @@ f-strings - Is the layout of the data written to file easier to understand? ::: ::: {.column width="50%"} ---> Configuration settings - There is helpfully a list of configurable inputs at the end of the file under `"__main__"`.\ We can improve on this, however, by placing them in a configuration file. - Create an appropriate json file to be read in as a dictionary and passed to the main function. - +--> ::: ::::