[Tutor] Feedback on coding style

[dn]

On 10/05/2022 00.01, Leam Hall wrote:
> Hey all,
> 
> I'm looking for general Python code critique, feel free to share snarky
> comments.  :)  The parameters are:
>  1. Code to Python 3.6 or so.
>  2. Use only the standard library or locally created modules.
>  3. Keep it clean and simple so new Pythonistas can understand and
> contribute.
> 
> Let me know how to make this better.


Apologies: was 'otherwise occupied' when this first hit the list. (and
you're not Swiss, German, or ... so will try to stay away from what may
seem like the 'snarky' way to reply)


- as a reader, will I be more-interested in the location of your PC's
python3 interpreter, the program[me]'s name, its version, origin-date,
author, or its desc[ription]?

- the university requires me to establish 'ownership' of all materials
in case they are (later) used in courseware, articles, books, etc. Thus
a rather legalistic line! Here is the standard 'base' used in a typical
toy-example used to illustrate a particular concept during a local
PUG-meeting:

<<<
""" Generator expression. """

__author__ = "David Neil, IT&T Consultant"
__copyright__ = "Copyright © 2022~"
__license__ = "May not be copied"
__python__ = "3.9"
>>>

Thus, an alternative to earlier suggestions of 'bundling' everything
into a single docstring: the module docstring is separate, and each of
these items is retrievable. Herewith:

>>> import tuple_comprehension_demo as tcd
>>> help( tcd )

Help on module tuple_comprehension_demo:

NAME
    tuple_comprehension_demo - Generator expression.

DATA
    __copyright__ = 'Copyright © 2022~'
    __license__ = 'May not be copied'
    __python__ = '3.9'
    student_names = ('fred', 'wiLma', 'bARNEy', 'bettY', 'Pete', 'dn')
    tuple_of_names = ('Fred', 'Wilma', 'Barney', 'Betty', 'Pete', 'Dn')

AUTHOR
    David Neil, IT&T Consultant

FILE
    /home/dn/Projects/AuckPUG-2022-04-20/tuple_comprehension_demo.py
>>>
PS I'll be interested to see what 'normal people' do for this...

- emphasising @Alan's comments: we (old-timers - me, not Alan!) used to
talk about Input-Process-Output, ie in order to produce the output
required, what processing will need to be done, and thus: what input(s)
will be needed. I suggest that this is still a valid approach to
decomposing a problem, and applies particularly well to the (two modes)
way this code is to work - in fact, consider adding a fourth 'phase':
'Establish the Environment' (all the argparse stuff which will define
which mode the user wishes to operate). Accordingly, the four 'phases'
guide us into a 'first-layer' thinking-about/designing, and then coding
solutions. More importantly (especially given the discussions about
flat-file, CSV, and SQL storage options), if the code is split into
*independent* sections, it becomes easy to change (or experiment with
changes/upgrades) because only the one section will be affected - and
the rest of the code should continue to operate (correctly, untouched,
in perfect splendor...)

- just because there was talk about options for persistence, I'll
throw-in the suggestion of MongoDB (or similar). NoSQL DBs are a lot
simpler to use than SQL (and I learned SQL before Oracle or SQL/DS (IBM
DB2) were even commercial products, and train in the subject to this
day!). More to the point, their data appears as if it was a Python
data-structure (a list in this case), so no need to bend-your-head
around much that is 'new'! (similar argument applies to JSON, YAML, etc)

- for SCM (source code management) there are several good tools (I don't
do CI/CD). I use git on my local machines, and for security-copies and
sharing, push and pull to my GitLab or others'. One of the perqs of
joining the local Open Source Society is access to a number of servers
and services. One of which is a GitLab instance. That Microsoft cannot
claim 'ownership' or otherwise use/make use of 'my' code (see legalism,
above) is an important legal, if not, moral component to my decision (or
that imposed upon me). GitLab.com tells us how much better (more mature)
their offering is than GitHub (perhaps 'the other guys' do the same, to
their benefit?), and outlines their $free/$paid service plans.

- should you move to SCM, then suggest review of the header-comments,
because dates and version-numbers become a function of the SCM rather
than a manual coding-process!

- recommend researching named-tuples
(https://docs.python.org/3/library/collections.html?highlight=namedtuple#collections.namedtuple)
then the datum can be given a less-generic name, eg
blood_pressure_reading; and the three components similarly identified.
Because each element of the tuple can be given its own name (hence the
"named", hah!) there is no need for packing/unpacking between int(s) and
the collection data-structure!

- reiterating: 'names' are important. (yes, this is a short and simple
module, but habits are hard to form - and all-to easy to slip) Thus,
generic terms such as "report", "result_string", and "report_list" seem
 obvious at the time of coding - but will require more
comprehension-effort (than necessary) at some (six-months in the) future
time-of-reading! With today's text-editors able to pop-up suggestions
for what we might be intending to type, identifier length (and thus
precision-naming) is hardly an issue (cf temptations towards
laziness/saving my worn-down fingers, ...)

- unlabelled lists of 'anything' decrease readability! Accordingly, when
it comes to function declarations (obvious example), after about two
parameters (IMHO) we should be using keyword-arguments. The problem with
format() (particularly in this example-code) is that it is preceded by a
bunch of empty braces, and these have to be positionally-related to some
code 'further over on the right' (of the code-line). Admittedly in this
case things are not too bad because tuple-unpacking is in-use - so we
don't have to keep track of four pairs of braces (on the left), and four
identifiers (on the right). [it's a lot of effort for aged eyes!]
Recommend researching f-strings
(https://docs.python.org/3/reference/lexical_analysis.html#f-strings).
The process becomes an expression (cf a function) but doesn't take much
learning because the same format() protocol is applied.

- finally, if you can persuade my at-home BP-machine to 'talk' to my
computer, sign me up! At this time, I would have to copy from my
bed-side scratch-pad into the PC, manually. (am too lazy for that!)
Which does lead to the observation that now() is only applicable if the
input is carried-out immediately after the BP-test - which saves adding
another input field, but there's a human involved...
-- 
Regards,
=dn