Naming conventions for function arguments in python

Question

Should the names of function arguments reflect the context of the function in which they are used? To give a concrete example in Python, (taken from this textbook):

def create_radio_button(rb_name, rb_value):

vs

def create_radio_button(name, value):

The Python style guide suggests using underscores to avoid keyword clashes, but doesn't mention the use of prefixes in arguments. In Clean Code, Bob Martin suggests choosing variable names that are pronounceable and to avoid encodings, which perhaps counts against an rb_ prefix. However, he follows this by stating that variable names should be searchable. My primary goal is to improve the clarity of my code, so I'm interested to hear what people have found easiest to work with.

Answer 1

It depends on context, and perhaps on personal preference to some extent.

def create_radio_button(name, value)

Recommend the above over the other option here, because I can see from the context that we are talking about a radio button so the "rb_" prefix is redundant information, it is already duplicated in the function name.

The comment about variable names being searchable I guess refers to the poor practice of using a variable name such as p, where you might want to search or highlight the variable name, resulting in the annoyance of finding any word containing a p. This issue doesn't apply so much here, "name" and "value" would be searchable enough*.

_{* This last point is somewhat moot for people using a decent editor, where we can refactor/rename a symbol and the IDE should be smart enough to know where the usages are in context/scope}

Answer 2

This is a more general question than just python. The parameter name should describe its role as concisely as possible (so I would just use "name" and "value" in your example). Of course, this doesn't replace actual documentation, for which I would recommend the somewhat standard tags

     :param name: description
     :param value: description

(you can also add the expected type of the parameter before its name in the above)

In general, the function should be relatively short, so it is fairly obvious that 'name' is a parameter to the function.

I think using the rb_ prefix would only make sense for global variables, which, in a python application, should be pretty rare (better use class variables).