Convention for specifying extensions in cabalized project

Question

For any .hs file, you can specify the language extensions you rely on like so:

{-# LANGUAGE Foo, Bar, Baz #-}

A cabalized project can also specify language extensions on a per-project basis in the .cabal file:

extensions: Foo, Bar, Baz

Which of these is considered "best practice"? Should all extensions used be listed in the .cabal file, as a form of documenting which compilers your package is compatible with? Or should all extensions be noted on a per-file basis, for the sake of making clear which files depend on which extensions? What about extensively documenting in both places? Or is best practice somewhere in-between?

Answer 1

It depends on how much they're used. If you use an extension in every module in your project, you might want to put it in your cabal file; for instance, if you use C preprocessor directives everywhere, it only makes sense to put CPP in your extensions field rather than listing it over and over, and if you have a lot of complicated instance declarations in your modules, it could be reasonable to put FlexibleInstances in there, too.

But "dangerous" extensions (like UndecidableInstances), and extensions only used in a few places, should go at the top of your file: the former for documentation (i.e. "here be dragons"), the latter for documentation and to keep the effects of extensions isolated, so you don't accidentally use an extension's effects where you didn't intend to in another module.

In general, I would err on the side of putting them at the top of the file, and only using the extensions field when specifying an extension over and over again gets annoying.