1

I have a method. The language for this question unimportant, but here are the stubs in Java and Python so people have something to relate to:

Token getToken(long seconds){
   ...
}

def get_token(seconds):
   ...

The documentation for this method reads:

Get the current token, or a new one.

Guarantees that the returned token will be valid for at least the given amount of seconds.

Since I am not a native english speaker, the two things are puzzling me.

I would like to name the argument for my method something more saying than seconds, but it should not be too long. I have considered the following (Python styled):

  • timeout_seconds
  • minimum_timeout_seconds
  • minimum_timeout
  • required_timeout
  • required_timeout_seconds

I don't think any of them are spot on, and the two of them are a bit long for my taste. What do people prefer? Is there a word that can express the purpose better than the ones I have used?

Secondly, the documentation for the argument reads:

The number of seconds there should at least be left until the current token expires. If there is less than this number of seconds left until expiration, the token will be renewed automatically.

I don't feel the wording here is right. Any thoughts?

beruic
  • 5,517
  • 3
  • 35
  • 59

1 Answers1

1

As you are dealing with tokens I'd Take the JSON Web Token (JWT) RFC as inspiration. Hence I would use

expires_in_seconds

as the variable name if keeping with Python styling.

The word "timeout" is more commonly used when an operation ceases to try to succeed in whatever it is trying to do, whereas "expires" indicates that the subject (in this case a token) is coming to the end of its period of validity.

As for the documentation I'd rather:

The number of seconds for which the token is valid.

However it does feel like the code you are using maybe trying to create it's own web token standard, which is something I would warn against! e.g. "If there is less than this number of seconds left until expiration, the token will be renewed automatically" seems odd.

Community
  • 1
  • 1
Ben Smith
  • 19,589
  • 6
  • 65
  • 93
  • 1
    It's for headless access to (among other things) oauth2 tokens, necesary for RPA-like and other automation robots dealing with API access only. I think "The number of seconds for which the token must be valid" is better, because it's about making a guarantee for the calling process. – beruic Apr 30 '19 at 08:19
  • How do you feel about using a term as `timeout_padding` or `expiration_padding`? – beruic Apr 30 '19 at 14:28
  • Padding is usually used when you are extending something. In this case your get_token method is not extending the length of the tokens life, it is creating it, so I wouldn't use padding (nor timeout for the same reason I've given before). – Ben Smith Apr 30 '19 at 19:47
  • I guess you are right that 'padding' is the wrong word to use for those reasons. I just wish i knew the right word. Right now I'm considering `expiration_warranty` – beruic Apr 30 '19 at 21:47
  • Naming is subjective and also comes down to personal preference. As discussed I'd find inspiration from authoritative sources. Good luck. – Ben Smith Apr 30 '19 at 23:38
  • 1
    Thank you. The issue lies in finding these authorative sources, and thus my need to ask here ;) – beruic May 01 '19 at 07:28