-2

I'd like to document that code encapsulated in a class is "time-based" in a Java-like language – the code behaves differently based on what time it is currently. To make it testable, it would read from a TimeProvider interface or something similar.

  1. Should this documentation be done through an interface or just as function or property on the time-dependent class?
  2. If so, what noun would be appropriate as an interface name to document the fact that the class is time based?
2

Unless the purpose of the class is to provide the date and time to other classes, the class should not depend on the time, at all. It should depend on data. And the time should be provided to it as data. So for example the class could accept an injection of a service that exposes a method or property that returns the date and time. The class should not directly access the system clock at all.

If you do it this way, you can substitute a different service if, for example, you wish to test the system with a simulated or hardcoded time to test boundary conditions.

So the question becomes-- how do I indicate that a class that behaves differently based on the data that is provided to it? And the answer is... nothing, really, because pretty much all classes do that.

  • Yes, a class would get a TimeProvider injected. The question is whether this injection should be documented via a contract, like a TimeBased interface. – ipavlic Oct 22 '18 at 23:39
  • My point is that there is no difference between a class that depends on time and a class that depends on any other kind of data. So the answer is no, it is not documented via contract. – John Wu Oct 23 '18 at 0:09
1

Should this documentation be done through an interface or just as function or property on the time-dependent class?

Neither.

The dependency on time is important only in a context of the tests. You don't document your code for the tests; you write tests to document your code.

Outside the testing context, either the fact that the code depends on the current time is not particularly interesting, in which case, no specific documentation is needed, or it does matter, in which case the quantity and content of the documentation will strongly depend on the actual business case. It could be as simple as a name of a method:

const getUsageForToday = function () {
    ...
};

or as complicated as a detailed comment explaining that a specific method is behaving a bit differently when being called from UK during DST just after midnight while using a server hosted at NYC and configured at GMT-5.

If so, what noun would be appropriate as an interface name to document the fact that the class is time based?

It all depends on the business context. Again, if it makes sense to emphasize the importance of time, then you'll (relatively) easily find how to name it. If not, then don't bother introducing a detail that the developers using your code won't need to know.

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.