Why I do not doc quirks of a function on the function itself.

Each product supervisor is aware of this example:

• A consumer works with function X1.
• They discover a limitation / bug / quirk and need to work round it.
• The proper workaround or different is function X2, however with out figuring out that X2 exists, the consumer doesn’t discover it and spends loads of time searching for it.
• The consumer requests X2 be documented on X1, as a result of that may have saved them a ton of time.

That is such a typical sample, and whereas it’s completely comprehensible for such a consumer to request this, it’s so terribly incorrect to offer in to this consumer’s request. Why is it incorrect?

The options are unrelated

More often than not, the 2 options X1 and X2 are unrelated and simply “occur” to be related on this particular consumer’s scenario. Let’s take jOOQ, for instance. Think about you’re employed with the SUM(X) mixture perform. For historic causes, this perform (like many different arithmetic features) returns BigDecimal in jOOQ, so it gained’t overflow, regardless of the enter kind. The signature of the perform is:

public static AggregateFunction<BigDecimal> sum(
    Area<? extends Quantity> subject
) { ... }

This will or will not be a very good factor. In any case, individuals are used to generics in jOOQ’s API, so they could have most popular this signature as an alternative (which dangers overflowing for varieties like TINYINT / Byte):

public static <T extends Quantity> AggregateFunction<T> sum(
    Area<T> subject
) { ... }

So, function X1 is SUM(X). The “quirk” is that it could return an sudden kind. (The quirk is controversial. The related subject to deal with this isn’t very talked-about, so it could simply as nicely be fantastic).

Now, for some customers preferring the choice signature, function X2 is the coerce() perform, a jOOQ perform that works like a SQL solid(), however doesn’t impression generated SQL. It’s carried out fully within the consumer. Although, solid() would additionally work right here.

For instance, to get an Integer sum:

// As a substitute of:
Record1<BigDecimal> r1 = ctx
    .choose(sum(TABLE.COLUMN))
    .from(TABLE)
    .fetchOne();

// Get this (the place SQLDataType.INTEGER is used):
Record1<Integer> r2 = ctx
    .choose(sum(TABLE.COLUMN).coerce(INTEGER))
    .from(TABLE)
    .fetchOne();    

coerce() is such a helpful function X2 in jOOQ, it’s most likely value figuring out about it in the event you’re a jOOQ energy consumer. It isn’t associated to X1 (the SUM(X) mixture perform), though it helps work round a “downside” (or quirk / historic API design alternative / and so on.) that’s particular to SUM(X) (and dozens of different arithmetic features).

The function is unknown

However the issue a consumer may need is that this:

• Customers don’t have any downside discovering SUM(X), the X1. Each supported SQL perform has a corresponding jOOQ methodology in DSL, and jOOQ customers are shortly skilled to look there for something they already know from SQL.
• Customers do have an issue discovering out the right way to coerce() or solid() a knowledge kind, first as a result of 1) they could not know (or have forgotten, or are unable to attach) the idea, and a couple of) it’s merely not associated to the consumer’s job at hand.

So, loads of time could also be spent searching for an answer. With out figuring out what the most effective resolution is, options could also be explored. Within the worst case, these options additionally trigger (unrelated!) points, and the much more irritating XY downside ensues.

Even with out the XY downside, loads of time could also be wasted searching for the answer X2.

The urge to doc

If the consumer ultimately finds out about X2 (the coerce() perform), they could request that X2 be documented on X1, as a result of that may have actually helped them. And there’s little doubt that this sort of documentation would have helped this specific consumer.

BUT!

Most customers who work with SUM(X) don’t must know something about coerce(). They’re completely pleased with BigDecimal, or alternatively, they could have discovered a wholly totally different strategy to turning BigDecimal into Integer (e.g. BigDecimal::intValue) they usually’re completely pleased with their resolution X3.

If X2 was documented on X1, for many customers, that may have simply been noise. Maybe it’s not horrible noise however:

• It’s a primary little bit of noise on X1 about an unrelated function X2.
• The following consumer will discover X2 to be inadequate for his or her downside and would need to have X3 documented as nicely.
• The following consumer will discover a wholly totally different limitation in X1 and can need to have their workaround X4 documented as nicely (for instance, the truth that SUM(X) returns NULL as an alternative of the identification worth 0 for empty enter units, a typical SQL “quirk”).
• The following consumer may have a limitation on X5 and can need to have X1 and X6 documented there.

The set of options X = {X1, X2, ..., Xn} is giant, and if a product is designed nicely and has loads of extremely reusable elements, like jOOQ, then in precept, virtually each function can work together with each different function.

That is already arduous sufficient to check, but when each mixture additionally needs to be documented together with an inventory of quirks, caveats, gotchas, workarounds, and so on. then we’ll by no means cease documenting issues that 99% of customers won’t ever must know and thus understand as noise.

As an excessive instance: Think about a consumer who has to move a Checklist<T> to methodology(Checklist<T>). However they’re unaware of ArrayList. Not solely do they request ArrayList be documented on methodology(), but additionally the truth that an ArrayList will be created utilizing new. It’s completely unrelated noise!

There could be a lot noise that our consumer who wished X2 (the coerce() perform) to be documented on X1 (the SUM(X) mixture perform) wouldn’t even discover this bit of knowledge within the limitless listing of quirks. Evidently that shifting that specific quirk to the highest of the listing of quirk isn’t going to be the correct resolution to discovering this bit of knowledge.

So, what’s one of the best ways to assist this consumer?

Personally, I like Stack Overflow. Folks understand the moderation as harsh, however the large advantage of this moderation is that good questions are at all times very particular and thus helpful for the subsequent consumer who finds the query on Google. It’s completely fantastic to ask concerning the mixture of X1 and X2 on Stack Overflow. Whereas the options are unrelated, the mixture does assist this specific consumer. So if this consumer asks:

I need to use X1, however I bumped into this quirk. How can I work round it?

Then I might reply:

Use X2 as a workaround. Right here’s how: [ … ]

That is a lot a lot better than documentation on the Javadoc or within the handbook:

• It doesn’t generate noise. 99% of jOOQ customers aren’t involved with this Q&A, so they are going to by no means Google it, and thus by no means encounter this query. So, they’re joyful.
• It’s extremely particular. The 1% of jOOQ customers who do have the identical query will discover this reply on Stack Overflow (or ChatGPT & co, which plagiarise Stack Overflow), so that they’re joyful as nicely.

Conclusion

Documenting quirks is a slippery slope. As a product grows and matures, it accumulates quirks. There aren’t any exceptions to this. Documenting all of those quirks someplace is vital, as a result of customers who run into them will need solutions.

Documenting these quirks on the function documentation itself isn’t the correct alternative, nevertheless, as a result of most customers gained’t be involved with the quirk. The listing of documented quirks will shortly turn into overwhelming.

A Q&A of some type is often the most effective strategy, be it:

• A query on Stack Overflow
• A problem on a problem tracker with a associated dialogue concerning the quirk and all of the attainable workarounds