1

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?

  • 8
    If it describes the purpose well and everyone will / should be able to understand it, what are you worried about? The name is for you and other programmers to read. Pick whatever best conveys the purpose. – Becuzz Oct 26 '16 at 18:04
  • 5
    "stimulus" is not a word I find uncommon. – MetalMikester Oct 26 '16 at 18:07
  • 1
    @MetalMikester It's not a work I'd consider uncommon in general; I haven't ever seen it used in this context to describe something like this (not that I have a particular problem with it, just saying the OP's concerns may at least be worth considering). – Servy Oct 26 '16 at 18:09
  • @Servy I don't know. It seems clear to me, but I'm having a weird day. – MetalMikester Oct 26 '16 at 18:12
  • 1
    "stimulus" looks fine to me, but if you do not like it, you could also write "trigger", as long as you are not working in a database context where the latter could be intermixed with database triggers. – Doc Brown Oct 26 '16 at 20:57
10

Formal parameter names should correctly reflect the domain in which they operate.

In your case, the word "stimulus" is a commonly used and understood term within the domain of Finite State Machines, so its use is appropriate here.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.