Agree. And in a richly-typed language you can be more specific: getUserDetails :: UserID -> DBAction (Maybe AnyUser) This type says a lot already. The def

Agree. And in a richly-typed language you can be more specific: getUserDetails :: UserID -> DBAction (Maybe AnyUser) This type says a lot already. The definition of `AnyUser` would specify the parameters that the comment only says in prose. Or we could be more specific getActiveUserDetails :: UserID -> DBAction (Maybe ActiveUser) We could also include the authorization specification in the type constraints on the `DBAction`: getUserDetails :: (DBAction m, HasAdminContext m) => UserID -> m (Maybe AnyUser) This is what I mean when I say that a rich type system can enforce a lot of what you might traditionally use comments for in a weaker type system. Now my hypothetical comment might highlight some salient points about this function, such as performs N queries to validate all of the available authorization contexts, use with a user role that has a limited number of contexts for best performance.