All methods must have the same arguments as the generic

You can see that the method for pointset class, centroid.pointset() has a weights argument, even though it is not used because weights are already contained in the coords object. This seems clunky and potentially confusing for users. But this is mandatory because all methods must have the same arguments as the generic.

Another option here could have been to remove weights from the generic, and add ... instead, thus allowing to pass weights as an extra argument only in selected methods. This is more idiomatic in R, and in line with the recommendation from the official ‘Writing R Extensions’ document (“always keep generics simple”):

#' @export
centroid <- function(coords, ...) { 
  UseMethod("centroid") 
}

#' @rdname centroid
#' 
#' @export
centroid.default <- function(coords, weights, ...) {

  coords_mat <- do.call(rbind, coords)
  
  return(apply(coords_mat, 2, weighted.mean, w = weights))
  
}

But this extra ... argument, which is documented as “ignored”, may be confusing as well.

More complex documentation presentation

On the topic of arguments, another pitfall related to the conversion to an S3 generic is the change in the documentation. Below is a collage of before / after the change. This is quite minor and some users may not even notice it but I remember it was very confusing to me when I started using R and I didn’t really know what S3 or OO was: “what do you mean, ‘Default S3 method’, which case applies to me?”

The answer is that “Default S3 method” lists the arguments for centroid.default(), i.e., the method which is used if no other method is defined for your class. Arguments for all methods are usually documented together but you should only focus on those present in the call after the comment stating “S3 method for class ‘XXX’” for the class you’re working with.

More complicated error traceback

Another situation where converting to an S3 adds an extra layer of complexity is where you are trying to follow the error traceback:

centroid(3)

In this example, we see one extra line that did not exist when centroid() was a regular function, rather than a generic:

centroid.default(3) at centroid.R#19

This line corresponds to the dispatch operation.

However, this slight difference in behaviour is likely not a big issue as we mostly expect experienced users to interact with the traceback. These users are likely to be familiar with S3 dispatch and understand the traceback in any case.

Extra source of bugs during dispatch

On a related note, the extra step introduced by this conversion to generic is another potential source of bugs. This doesn’t really impact your users directly but it does mean that as a developer, you will maintaining slightly more complex code and you will need to be more careful when making any changes. However, as always, a robust testing suite should help you catch any error before it makes it to production.

Where should the generic live?

The generic should always live in the package implementing the actual computation in the function in the first place. For example, if you defined the original centroid() function in a package called geometryops, the S3 generic should also be defined in that package, not in the package defining the pointset class.

It is possible in theory to overwrite a function defined by another package with a generic (“overloading”). For example, we could overload base R table() function with:

table <- function(...) { 
  UseMethod(...)
}

table.default <- function(
  ...,
  exclude = if (useNA == "no") c(NA, NaN),
  useNA = c("no", "ifany", "always"),
  dnn = list.names(...), deparse.level = 1
) {

 base::table(
  ...,
  exclude = exclude,
  useNA = useNA,
  dnn = dnn
 )

}

But this is generally considered bad practice, and possibly rude ². As a rule of thumb, you should usually avoid:

• name collisions with functions from other packages (especially base or recommended package);
• light wrappers around a function from another package as this may be seen as an attempt to steal citations and credit.

Where should the methods live?

For methods, there is more flexibility than for generics. They could either in the package defining the class, or in the package defining the generic. Let’s present the practical setup in both cases, as well as each strategy pros & cons.

#' @export
plot.myclass <- function(x, y, ...) {
  
  # code for a beautiful plot for your custom class
  
}

DESCRIPTION

Imports:
  generics

fit.myclass.R

#' @export
#' @importFrom generics fit
fit.myclass <- function(x, ...) {
  # your code here
}

NAMESPACE

# Generated by roxygen2: do not edit by hand

S3method(fit,myclass)
importFrom(generics,fit)

DESCRIPTION

Suggests:
  generics

fit.myclass.R

#' @exportS3Method generics::fit
fit.myclass <- function(x, ...) {
  # your code here
}

NAMESPACE

# Generated by roxygen2: do not edit by hand

S3method(generics::fit,myclass)

#' @export
mygeneric <- function(x, ...) { 
  UseMethod(x)
}

#' @export
mygeneric.externalclass <- function(x, ...) {
  # your code here
}