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

Each product supervisor is aware of this case:

A person works with function X1.
They discover a limitation / bug / quirk and wish to work round it.
The right workaround or various is function X2, however with out realizing that X2 exists, the person doesn’t discover it and spends a whole lot of time in search of it.
The person requests X2 be documented on X1, as a result of that may have saved them a ton of time.

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

The options are unrelated

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

public static AggregateFunction sum(
    Area extends Quantity> area
) { ... }

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

public static  AggregateFunction sum(
    Area area
) { ... }

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

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

For instance, to get an Integer sum:

// As an alternative of:
Record1 r1 = ctx
    .choose(sum(TABLE.COLUMN))
    .from(TABLE)
    .fetchOne();

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

coerce() is such a helpful function X2 in jOOQ, it’s most likely price realizing about it in case you’re a jOOQ energy person. It isn’t associated to X1 (the SUM(X) combination operate), though it helps work round a “downside” (or quirk / historic API design selection / and so forth.) that’s particular to SUM(X) (and dozens of different arithmetic features).

The function is unknown

However the issue a person may need is that this:

Customers don’t have any downside discovering SUM(X), the X1. Each supported SQL operate has a corresponding jOOQ technique in DSL, and jOOQ customers are rapidly educated to look there for something they already know from SQL.
Customers do have an issue discovering out the best way to coerce() or solid() an information sort, first as a result of 1) they could not know (or have forgotten, or are unable to attach) the idea, and a pair of) it’s merely not associated to the person’s activity at hand.

So, a whole lot of time could also be spent in search of an answer. With out realizing what one of the best resolution is, alternate options could also be explored. Within the worst case, these alternate options additionally trigger (unrelated!) points, and the much more irritating XY downside ensues.

Even with out the XY downside, a whole lot of time could also be wasted in search of the answer X2.

The urge to doc

If the person ultimately finds out about X2 (the coerce() operate), they may 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 explicit person.

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 completely totally different method to turning BigDecimal into Integer (e.g. BigDecimal::intValue) and so they’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 person will discover X2 to be inadequate for his or her downside and would wish to have X3 documented as nicely.
The following person will discover a completely totally different limitation in X1 and can wish 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 standard SQL “quirk”).
The following person could have a limitation on X5 and can wish to have X1 and X6 documented there.

The set of options X = {X1, X2, ..., Xn} is massive, and if a product is designed nicely and has a whole lot of extremely reusable elements, like jOOQ, then in precept, nearly 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 forth. 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 person who has to cross a Record to technique(Record). However they’re unaware of ArrayList. Not solely do they request ArrayList be documented on technique(), 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 person who wished X2 (the coerce() operate) to be documented on X1 (the SUM(X) combination operate) wouldn’t even discover this bit of knowledge within the countless listing of quirks. For sure that transferring that specific quirk to the highest of the listing of quirk isn’t going to be the best resolution to discovering this bit of knowledge.

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

Personally, I like Stack Overflow. Individuals understand the moderation as harsh, however the massive advantage of this moderation is that good questions are all the time very particular and thus helpful for the subsequent person who finds the query on Google. It’s completely nice to ask in regards to the mixture of X1 and X2 on Stack Overflow. Whereas the options are unrelated, the mixture does assist this explicit person. So if this person asks:

I wish 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 blissful.
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), in order that they’re blissful as nicely.

Conclusion

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

Documenting these quirks on the function documentation itself isn’t the best selection, nonetheless, as a result of most customers received’t be involved with the quirk. The listing of documented quirks will rapidly change into overwhelming.

A Q&A of some type is normally one of the best method, be it: