I am implementing a finite state machine in Python 2.7, and I am considering using an English word that I don't commonly see in code: "stimulus". I have a transition function that accepts some kind of input and the current state to decide which state to transition to:
def transition(self, stimulus):
# each state class has a decode_next_state() method to decide
# what state to transition to based on the input
next_state = self.current_state.decode_next_state(stimulus)
I'm unsure about the use of the word "stimulus", because it's not something I commonly see in code. In this case, it could be a response from the system under test, it could be a timeout error, or it could be some other error code. I want the name to be descriptive, but "input" is a built-in function name, I don't think "message" correctly describes the different types of data, and alternatives like "impetus" are even less common.
How concerned should I be that this isn't a very common word? I work in a very language- and culturally-diverse workplace, with non-native English speakers, so I want to make sure I'm using clear language.
Just to make sure my question is clear: I've given one example of where I'm unsure about the appropriateness of a word that isn't common in code, but I don't necessarily want suggestions of words to use in this case. I'm seeking more general input on the idea of using descriptive but uncommon words, vs favoring more common words to make the code easier to understand.
TL;DR
In general, should I prefer common words and language constructs to enhance code maintainability/understandability, even when a less-common word better describes my variables?
