What I’m trying to do:
Choose a function or variable name. I want to make it clear to the developer (me, in 2 months!) that the value contains no Anvil-specific types or data, e.g., db links.
Such data is handy for
I’m sure it’ll seem obvious in retrospect, but my coffee hasn’t kicked in yet…
I usually do the opposite, I try to remember the future user (me) that the function or variable is specific to Anvil or whatever context. If there is no mention of any specific context, then it’s a generic one.
I have learned to use long, even very long names.
I add comments only when the code does something weird and not self-explanatory, like working around a bug or limitation. If the code is well written and the names are long enough, there is no need for comments.
Plus the comments have close to 100% chances of being ignored at the next code change and become stale.
For example, here I’m pushing it a little, but this gives an idea:
# this needs a comment, hence the function name is bad
#
# use this only on simple object columns
def row_to_json(row):
...
# this doesn't, much better, I will never misuse this
# function and never leave a stale comment
def row_to_json_for_simple_object_columns(row):
...
A common term from java was POJO - Plain Old Java Object. You could come up with something similar!
I also try to avoid comments as much as possible. I view needing them as a code smell suggesting a refactor is necessary.
However, I do use docstrings and type hints. Those appear in editors, get used by auto completers and reduce the need for those cumbersome names.
…and C++ has POD (Plain Ol’ Data). By analogy to POJO, a Plain Old Python Object would be a POPO…
As this is code that will be appearing inside an Anvil app. Anvil is the context, by default. Generic routines are the exception, in this app.
For Uplink code, though, which operates in a not-entirely-Anvil context, I definitely see the point.
Naming is intrinsically hard. We want to incorporate the distinctions that matter, and skip the ones that don’t. But “what matters” depends very much on the task at hand. New, unexpected tasks come up, raising the importance of new distinctions. Then we notice, the old names fail to make those new distinctions… This is probably one way that short names become long ones.
Plain Old Ordinary Python?
I agree 100%
I do admire people that can keep docstrings current!
I just can’t.
I sometimes try to use docstrings, but if I’m working with something recent, I don’t need them because I remember whatever they say, and if I’m working with something old, they are always stale and I end up with deleting them, because first they make me waste time thinking that the function does something that doesn’t do any longer, then I need to read the code anyway, then I need to update the docstring, which will inevitably get stale by the time I need it next.
So my strict policy is no docstrings, unless it’s a very long one that describes a class with many optional (not explicit) behaviors. This one will get stale too, but I found out that it still makes sense to carry along and invest some time to keep it current.
Type hints are ignored by Anvil, but they are useful in PyCharm or other environments. I usually start without them, but I then end up with sprinkling them around the code, where PyCharm would otherwise get confused.
A few years ago I bought a book about algorithms in Python. I don’t remember what book, because I threw it away. I remember why I threw it away: all code snippets had one-letter variable names, included the Hungarian notation prefixes, included type hinting, included a docstring. For example the docstring explained that the fx: float variable was a float with the diameter of something. Perhaps the book was good at describing those algorithms, but I will never know. It lost all my trust when, instead of calling a diameter diameter, it used docstring, type hinting and prefixes together with a meaningless x.
Re comments in code:
The code says how to do things. For why, I still find comments very useful.
100% agree. Name a variable after the value it represents, or the role it plays. Include dimensions and units of measure, where applicable.
Type hints are ignored by Anvil, but they are useful in PyCharm or other environments
Well, not if you fire up neovim from within the IDE!
I also loathe docstring formats which include a type along with type hints. Choose where to put that information and put it there and only there!
This developer/cartoonist said it much better than I…
I’m still never sure if this is real or not :