Faq.scalatex

@import Main._
@import org.scalafmt.readme.Readme._
@import org.scalafmt.config.ScalafmtConfig
@import org.scalafmt.config.ScalafmtConfig.default

@sect{FAQ / Troubleshooting}

   @sect{Why not Scalariform?}
     @lnk("Scalariform", "http://scala-ide.org/scalariform/") does an
     excellent job of tidying up common formatting errors. However,

     @ul
       @li
         Scalariform does not have a @code{maxColumn} setting, which
         I personally like and is present in many popular coding styles.
       @li
         Scalariform preserves most line breaking decisions, leaving it up to
         you (or even worse, your colleagues) to choose a formatting layout.
         Scalafmt takes liberty to add/remove newlines, making your entire
         codebase look consistent.

     Finally, scalafmt is my Master's thesis project. I thought it would
     be a fun challenge to write a code formatter :)

   @sect{Why is scalafmt so slow?}
     @p
       My benchmarks show that scalafmt is for most common cases around 4-6x
       slower than scalariform (btw, scalariform is already impressively fast).
       This means that formatting your average 1.000 LOC file on modern
       hardware will take around 200ms, which should still feel close enough
       to instant.

     @p
       The main feature that makes scalafmt slower than scalariform is the
       column-width limit.
       To figure the "best" way to break a long line, Scalafmt may try
       thousands of different formatting solutions.

     @p
       I am sure that scalafmt could benefit greatly from
       micro optimizations. Any help here is appreciated.

   @sect{Code formatters create unnecessary diffs!}
     @p
       That's not a question, but I agree that code formatters like scalafmt do
       sometimes increase the size of diffs in code reviews.
       I still believe it's worth it, considering

     @ol
       @li
         Proper formatting @lnk("helps you catch bugs", "https://twitter.com/extempore2/status/717716747181096960")!
       @li
         you can enable non-whitespace diffs during code review. For Github,
         add @code("?w=1") to the URL to ignore whitespace changes.
       @li
         @code{git blame} has a @code{-w} flag to ignore whitespace changes
         so you can still blame your colleagues for their crappy code.
       @li
         code is read waaay more often outside of code reviews, for example
         when you are actually coding.

   @sect{Which configuration options minimize diffs/conflicts in version control?}
     @ol
       @li
         @code("align=none")
         If alignment is enabled a renaming of one entity can impact the indentation of other entities.
       @li
         @code("danglingParenthesis=true")
         Having the closing parenthesis on the same line as the last argument makes the diff line include
         the parenthesis and everything following it in case that argument is renamed.
         So, technically this does not reduce the number of diff lines, but the length of them.

   @sect{Is the formatting output stable between releases?}
     No, the formatting rules will evolve even between PATCH releases.
     I recommend you inspect the diff for @b{every} scalafmt update.