Naming style for configuration properties defining durations in Ignite 3

[Roman Puchkovskiy <ro...@gmail.com>]

Hi Igniters!

In Ignite 3, in configuration schemas, we have some properties that
define durations/intervals (usually, these are timeout durations).
Almost always they are defined without mentioning the duration unit,
like this:

/** Node join timeout. */
@Value(hasDefault = true)
public int joinTimeout = 5_000;

This makes a user puzzled about the unit of measure: it might be
milliseconds (as it often is), but who knows.
It seems beneficial to include the unit of measure in names of such
properties, like joinTimeoutMs or joinTimeoutMillis.

We might try to solve this via documentation, but, when a property
name speaks by itself, we don't need to reach for the documentation at
all, so it still seems better to have it in a name (and, if you edit a
config file, reaching for documentation might be a bit more
time-consuming than navigating to a method javadoc in an IDE).

We could do one of the following:

1. Do not change the naming schema, just improve the documentation; we
might also establish a strong convention of always having all
durations in the same unit (like milliseconds) [there is a
disadvantage: if we add a property that is naturally measured in, say,
hours, we would still have to use millis, which would make
configuration very cumbersome with all these zeros]
2. Use short suffixes (ns/ms/sec/min/hr/days): joinTimeoutMs. There is
a problem with microseconds if we ever need them (how do we abbreviate
it according to this style?)
3. Use longer suffixes (nanos/micros/millis/secs/mins/hours/days):
joinTimeoutMillis. A bit longer than the previous one.
4. ... or something else?

What do you think?

Re: Naming style for configuration properties defining durations in Ignite 3

[Roman Puchkovskiy <ro...@gmail.com>]

It's an interesting idea. That would solve the problem for
configuration files (or other external representations of a
configuration, like JMX or whatnot). As for the Java API, we could
model durations with java.time.Duration instances, so it would be

/** Node join timeout. */
@Value(hasDefault = true)
public Duration joinTimeout = Duration.ofSeconds(5);

If the number of instances/allocations is a problem, we could apply
something like the Flyway pattern to cache the durations somewhere
inside configuration-related infrastructure code.

пн, 26 дек. 2022 г. в 21:12, Alexei Scherbakov <al...@gmail.com>:
>
> What about specifying dimensions in config, like
>
> joinTimeout=5s
>
> Internally it is always stored in millis.
>
>
> пт, 23 дек. 2022 г. в 11:53, Pavel Tupitsyn <pt...@apache.org>:
>
> > Agree with the proposal.
> > Those properties go into config files (json/hocon), and it is difficult to
> > navigate to relevant docs from there.
> >
> > I would go with point 3 - longer suffixes like Millis - to make it
> > unambiguous.
> >
> > On Fri, Dec 23, 2022 at 10:06 AM Roman Puchkovskiy <
> > roman.puchkovskiy@gmail.com> wrote:
> >
> > > Hi Igniters!
> > >
> > > In Ignite 3, in configuration schemas, we have some properties that
> > > define durations/intervals (usually, these are timeout durations).
> > > Almost always they are defined without mentioning the duration unit,
> > > like this:
> > >
> > > /** Node join timeout. */
> > > @Value(hasDefault = true)
> > > public int joinTimeout = 5_000;
> > >
> > > This makes a user puzzled about the unit of measure: it might be
> > > milliseconds (as it often is), but who knows.
> > > It seems beneficial to include the unit of measure in names of such
> > > properties, like joinTimeoutMs or joinTimeoutMillis.
> > >
> > > We might try to solve this via documentation, but, when a property
> > > name speaks by itself, we don't need to reach for the documentation at
> > > all, so it still seems better to have it in a name (and, if you edit a
> > > config file, reaching for documentation might be a bit more
> > > time-consuming than navigating to a method javadoc in an IDE).
> > >
> > > We could do one of the following:
> > >
> > > 1. Do not change the naming schema, just improve the documentation; we
> > > might also establish a strong convention of always having all
> > > durations in the same unit (like milliseconds) [there is a
> > > disadvantage: if we add a property that is naturally measured in, say,
> > > hours, we would still have to use millis, which would make
> > > configuration very cumbersome with all these zeros]
> > > 2. Use short suffixes (ns/ms/sec/min/hr/days): joinTimeoutMs. There is
> > > a problem with microseconds if we ever need them (how do we abbreviate
> > > it according to this style?)
> > > 3. Use longer suffixes (nanos/micros/millis/secs/mins/hours/days):
> > > joinTimeoutMillis. A bit longer than the previous one.
> > > 4. ... or something else?
> > >
> > > What do you think?
> > >
> >
>
>
> --
>
> Best regards,
> Alexei Scherbakov

Re: Naming style for configuration properties defining durations in Ignite 3

[Alexei Scherbakov <al...@gmail.com>]

What about specifying dimensions in config, like

joinTimeout=5s

Internally it is always stored in millis.


пт, 23 дек. 2022 г. в 11:53, Pavel Tupitsyn <pt...@apache.org>:

> Agree with the proposal.
> Those properties go into config files (json/hocon), and it is difficult to
> navigate to relevant docs from there.
>
> I would go with point 3 - longer suffixes like Millis - to make it
> unambiguous.
>
> On Fri, Dec 23, 2022 at 10:06 AM Roman Puchkovskiy <
> roman.puchkovskiy@gmail.com> wrote:
>
> > Hi Igniters!
> >
> > In Ignite 3, in configuration schemas, we have some properties that
> > define durations/intervals (usually, these are timeout durations).
> > Almost always they are defined without mentioning the duration unit,
> > like this:
> >
> > /** Node join timeout. */
> > @Value(hasDefault = true)
> > public int joinTimeout = 5_000;
> >
> > This makes a user puzzled about the unit of measure: it might be
> > milliseconds (as it often is), but who knows.
> > It seems beneficial to include the unit of measure in names of such
> > properties, like joinTimeoutMs or joinTimeoutMillis.
> >
> > We might try to solve this via documentation, but, when a property
> > name speaks by itself, we don't need to reach for the documentation at
> > all, so it still seems better to have it in a name (and, if you edit a
> > config file, reaching for documentation might be a bit more
> > time-consuming than navigating to a method javadoc in an IDE).
> >
> > We could do one of the following:
> >
> > 1. Do not change the naming schema, just improve the documentation; we
> > might also establish a strong convention of always having all
> > durations in the same unit (like milliseconds) [there is a
> > disadvantage: if we add a property that is naturally measured in, say,
> > hours, we would still have to use millis, which would make
> > configuration very cumbersome with all these zeros]
> > 2. Use short suffixes (ns/ms/sec/min/hr/days): joinTimeoutMs. There is
> > a problem with microseconds if we ever need them (how do we abbreviate
> > it according to this style?)
> > 3. Use longer suffixes (nanos/micros/millis/secs/mins/hours/days):
> > joinTimeoutMillis. A bit longer than the previous one.
> > 4. ... or something else?
> >
> > What do you think?
> >
>


-- 

Best regards,
Alexei Scherbakov

Re: Naming style for configuration properties defining durations in Ignite 3

[Pavel Tupitsyn <pt...@apache.org>]

Agree with the proposal.
Those properties go into config files (json/hocon), and it is difficult to
navigate to relevant docs from there.

I would go with point 3 - longer suffixes like Millis - to make it
unambiguous.

On Fri, Dec 23, 2022 at 10:06 AM Roman Puchkovskiy <
roman.puchkovskiy@gmail.com> wrote:

> Hi Igniters!
>
> In Ignite 3, in configuration schemas, we have some properties that
> define durations/intervals (usually, these are timeout durations).
> Almost always they are defined without mentioning the duration unit,
> like this:
>
> /** Node join timeout. */
> @Value(hasDefault = true)
> public int joinTimeout = 5_000;
>
> This makes a user puzzled about the unit of measure: it might be
> milliseconds (as it often is), but who knows.
> It seems beneficial to include the unit of measure in names of such
> properties, like joinTimeoutMs or joinTimeoutMillis.
>
> We might try to solve this via documentation, but, when a property
> name speaks by itself, we don't need to reach for the documentation at
> all, so it still seems better to have it in a name (and, if you edit a
> config file, reaching for documentation might be a bit more
> time-consuming than navigating to a method javadoc in an IDE).
>
> We could do one of the following:
>
> 1. Do not change the naming schema, just improve the documentation; we
> might also establish a strong convention of always having all
> durations in the same unit (like milliseconds) [there is a
> disadvantage: if we add a property that is naturally measured in, say,
> hours, we would still have to use millis, which would make
> configuration very cumbersome with all these zeros]
> 2. Use short suffixes (ns/ms/sec/min/hr/days): joinTimeoutMs. There is
> a problem with microseconds if we ever need them (how do we abbreviate
> it according to this style?)
> 3. Use longer suffixes (nanos/micros/millis/secs/mins/hours/days):
> joinTimeoutMillis. A bit longer than the previous one.
> 4. ... or something else?
>
> What do you think?
>