Best practice on properly supporting OffsetArrays (#281)

Author: johnnychen94

README.md

@@ -132,6 +132,49 @@ julia> Origin(AO)(D)
 
 Here, `Origin(AO)` is able to automatically infer and use the indices of `AO`.
 
+## Best practice on adopting OffsetArrays
+
+For some applications, OffsetArrays give users an easy-to-understand interface. However, handling
+the non-conventional axes of OffsetArrays requires extra care. Otherwise, the code might
+error, crash, or return incorrect results. You can read [the Julialang documentation on
+offset](https://docs.julialang.org/en/v1/devdocs/offset-arrays/) for more information. Here
+we briefly summarize some of the best practices for users and package authors.
+
+### There is no need to support OffsetArrays for every function
+
+You don't need to support offset arrays for _internal functions_ that only consume standard 1-based
+arrays -- it doesn't change or improve anything.
+
+You don't need to support offset arrays for functions that _have no well-defined behavior on custom
+axes_. For instance, many linear algebra functions such as matrix multiplication `A * B` does not
+have an agreed behavior for offset arrays. In this case, it is a better practice to let users do the
+conversion.
+
+The helper function `Base.require_one_based_indexing` can be used to early check the axes and throw
+a meaningful error. If your interface functions do not intend to support offset arrays, we recommend
+you add this check before starting the real computation.
+
+### use `axes` instead of `size`/`length`
+
+Many implementations assume the array axes start at 1 by writing loops such as `for i in
+1:length(x)` or `for i in 1:size(x, 1)`. A better practice is to use `for i in eachindex(x)` or `for
+i in axes(x, 1)` -- `axes` provides more information than `size` with no performance overhead.
+
+Also, if you know what indices type you want to use, [`LinearIndices`][doc_LinearIndices] and
+[`CartesianIndices`][doc_CartesianIndices] allow you to loop multidimensional arrays efficiently
+without worrying about the axes.
+
+### test against OffsetArrays
+
+For package authors that declare support for `AbstractArray`, we recommend having a few test cases
+against `OffsetArray` to ensure the function works well for arrays with custom axes. This gives you
+more confidence that users don't run into strange situations.
+
+For package users that want to use offset arrays, many numerical correctness issues come from the
+fact that `@inbounds` is used inappropriately with the 1-based indexing assumption. Thus for debug
+purposes, it is not a bad idea to start Julia with `--check-bounds=yes`, which turns all `@inbounds`
+into a no-op and uncover potential out-of-bound errors.
+
 <!-- badges -->
 
 [pkgeval-img]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/O/OffsetArrays.svg
@@ -147,3 +190,7 @@ Here, `Origin(AO)` is able to automatically infer and use the indices of `AO`.
 [docs-stable-url]: https://juliaarrays.github.io/OffsetArrays.jl/stable/
 [docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
 [docs-dev-url]: https://juliaarrays.github.io/OffsetArrays.jl/dev/
+
+
+[doc_LinearIndices]: https://docs.julialang.org/en/v1/base/arrays/#Base.LinearIndices
+[doc_CartesianIndices]: https://docs.julialang.org/en/v1/base/arrays/#Base.IteratorsMD.CartesianIndices