Readability is often strongly tied with the expressivity and naming of variables within one’s code. A badly named variable is prone to confuse, and make Pull Requests and Merge Requests quite lengthy and painful.
What about enforcing the naming during usage of function key-word arguments?
Consider this function signature:
def upload_file_to_s3(filepath, bucket, key: Union[str, pathlib.PosixPath], s3):
"""Upload file to S3 buckets."""
...
and its usage:
upload_file_to_s3(
a,
b.bucket_data,
os.path.join(b.s3path_conf, a.name),
context.resources.s3
)
We must agree that these variables are terribly named a
, b
, etc… it’s just bad. But unfortunately, unless we catch these badly named variables during the code review, there isn’t much we can do about it in terms of automated stylistic linting (Unless I’m mistaken, but for the sake of this example let’s say there isn’t). An option is to add some readability during function calls.
Consider this alternative of calling this function:
upload_file_to_s3(
filepath=a,
bucket=b.bucket_data,
key=os.path.join(b.s3path_conf, a.name),
s3=c.resources.s3
)
Here, despite the badly named variables, I know a
is supposed to be a filepath, b
some object that contains s3
info, and what’s more, I can see how they are combined in the key
parameter, right away.
If during the continuous integration we have a PEP rule that warns us about a function’s use that doesn’t explicitely name its kwargs, it could go a long way into adding more readability to something as ubiquitous as function calls in python code.
In conclusion, here is what I’m proposing :
- Creating a PEP rule that, when we call a function, checks if its signature has named parameters, and warns us when they are not explicitely included in the function call. Catching this in a C.I pipeline is significantly easier than arguing with teammates over variable names in each PR/MR.
What do you think of my proposal?