| A few years ago I start a dashboard project that was mostly raw SQL. I then saw the team wanting to convert it to ActiveRecord, which they started. But lots of queries had to use AREL (Rails' "low level SQL AST abstraction"), since they weren't really possible or just too difficult to do in ActiveRecord. But AREL is so incredibly unreadable that every single AREL query often had its equivalent in plain SQL above it, as documentation, so new people could understand what the hell it was doing. In the end some junior was unhappy with the inconsistent documentation and petitioned that every query, simple or complex, AREL or ActiveRecord, had to be documented using SQL above the AREL/AR code. Then they discovered that documenting using Heredocs rather than "language comments" enabled SQL syntax highlighting in their editors. After that we had both: heredocs with the cute SQL and some unreadable AREL+AR monstrosity right below it. I still laugh about this situation when I remember it. |