Active Record Validations and Callbacks guide: validates vs validation helper methods

rubyonrails-docs
1

The "Active Record Validations and Callbacks" documentation in:

  http://guides.rubyonrails.org/active_record_validations_callbacks.html

uses the basic 'validates' call throughout. It was my understanding that the recommended practice was to use the helper methods described in:

    ActiveModel::Validations::HelperMethods

when possible. Has that changed? If not, perhaps the examples should be re-cast to use the helper methods. At the very least, a pointer to the existence of the helper methods would be helpful.

2

This guide was recently updated to be the inverse, where the “validates” syntax is preferred over the alternatively, possibly because with it you can specify multiple types of validations for the same field.

I agree that there should be mentions of the helper methods on that page. Could you please submit a patch to the documentation to that effect?

Thanks!

3

Usage of old-style validation macros is discouraged, the new validates macro is the way to go.

Documentation has the implicit goal of showing the recommended idioms by putting emphasis and obviating some valid but not-recommended stuff in examples across the docs.

With all that in mind, since the old-style macros are not formally deprecated, you could put a short new section as the last one related to validations saying that there are some old-style macros, linking to the API (rather than expanding them in the guide), and saying that their usage is discouraged nowadays.

Alternatively the guide could remain as it is, since old-style validation macros are there because of backwards compatibility mostly. It is OK that they appear in the API, but top-down docs like guides do not need to be exhaustive in that sense, they better explain how things are done today.