git-annex/ coding style

If you do nothing else, avoid use of partial functions from the Prelude! `import Utility.PartialPrelude` helps avoid this by defining conflicting functions for all the common ones. Also avoid `!!`, it's partial too.

Use tabs for indentation. The one exception to this rule are the Hamlet format files in `templates/*`. Hamlet, infuriatingly, refuses to allow tabs to be used for indentation.

Code should make sense with any tab stop setting, but 8 space tabs are the default. With 8 space tabs, code should not exceed 80 characters per line. (With larger tabs, it may of course.)

Use spaces for layout. For example, here spaces (indicated with `.`) are used after the initial tab to make the third test line up with the others.

        when (foo_test || bar_test ||
        ......some_other_long_test)
            print "hi"

As a special Haskell-specific rule, "where" clauses are indented with two spaces, rather than a tab. This makes them stand out from the main body of the function, and avoids excessive indentation of the where cause content. The definitions within the where clause should be put on separate lines, each indented with a tab.

    main = do
        foo
        bar
        foo
      where
        foo = ...
        bar = ...

Where clauses for instance definitions and modules tend to appear at the end of a line, rather than on a separate line.

    module Foo (Foo, mkFoo, unFoo) where
    instance MonadBaseControl IO Annex where

When a function's type signature needs to be wrapped to another line, it's typical to switch to displaying one parameter per line.

    foo :: Bar -> Baz -> (Bar -> Baz) -> IO Baz

    foo'
        :: Bar
        -> Baz
        -> (Bar -> Baz)
        -> IO Baz

Note that the "::" then starts its own line. It is not put on the same line as the function name because then it would not be guaranteed to line up with the "->" at all tab width settings. Similarly, guards are put on their own lines:

    splat i
        | odd i = error "splat!"
        | otherwise = i

Multiline lists and record syntax are written with leading commas, that line up with the open and close punctuation.

    list =
        [ item1
        , item2
        , item3
        ]

    foo = DataStructure
        { name = "bar"
        , address = "baz"
        }

Similarly, data structures line up the leading `=` with the following `|`

    data Foo
        = Bar
        | Baz
        | Quux Foo
        deriving (Eq, Ord)

Module imports are separated into two blocks, one for third-party modules, and one for modules that are part of git-annex. (Additional blocks can be used if it makes sense.)

Using tabs for indentation makes use of `let .. in` particularly tricky. There's no really good way to bind multiple names in a let clause with tab indentation. Instead, a where clause is typically used. To bind a single name in a let clause, this is sometimes used:

    foo = let x = 42
        in x + (x-1) + x

If you feel that this coding style leads to excessive amounts of horizontal or vertical whitespace around your code, making it hard to fit enough of it on the screen, consider finding a better abstraction, so the code that does fit on the screen is easily understandable. ;)

Note for emacs users: You can put the following snippet into a file called `.dir-locals.el` at root of git-annex's source tree to use tabs for indentation:

    ((nil . ((indent-tabs-mode . t)
             (tab-width . 8)
             (fill-column . 80)))
     ;; Warn about spaces used for indentation:
     (haskell-mode . ((eval . (highlight-regexp "^ *")))))

Also consider haskell-tab-indent-mode. The standard indentation modes that come with haskell-mode do not work well with tabs for indentation. This mode works well for hacking on git-annex.

man page style

Well, I don't always word-wrap paras when re-editing them, and several people have had their hands on the man page and may have different wrapping settings.

My suggestion would be, if you need to re-wrap, or generally make whitespace changes, do it in a separate commit from other changes. Similarly, make spelling corrections in a separate commit from any substance changes.

Note that you can push man page commits directly to this site via git:// protocol, so it's not going to use my time as long as there's a reasonable commit message.

Use backticks around any command name or fragment of a command line. Use quotes around program output, or other values that are not command names or switch names.

Comment by joey — Tue Jul 22 18:11:47 2025
Style for man pages?

Could you add some suggestions for editing the .mdwn files? I'd like to help clean up a few (really minor) things I noticed, but I don't want to make more work for you with the changes I make. One thing I'm not sure about is where to set my fill column when editing--I can't seem to pick any single value (79? 80?) that doesn't make some paragraphs change when I rewrap them. Also, it might be helpful to have a quick guide for when you surround commands and other computer-y words with quotes, backticks, or nothing at all.

Comment by Don — Tue Jul 22 18:11:47 2025
comment 2
safe does not prevent using the unsafe prelude functions. Utility.PartialPrelude does, and provides a few safe wrappers like lastMaybe.
Comment by http://joeyh.name/ — Tue Jul 22 18:11:47 2025
What about safe?

https://hackage.haskell.org/package/safe

> A library wrapping Prelude/Data.List functions that can throw exceptions, such as head and !!. Each unsafe function has up to four variants, e.g. with tail:

>     tail :: [a] -> [a], raises an error on tail [].

>     tailMay :: [a] -> Maybe [a], turns errors into Nothing.

>     tailDef :: [a] -> [a] -> [a], takes a default to return on errors.

>     tailNote :: String -> [a] -> [a], takes an extra argument which supplements the error message.

>     tailSafe :: [a] -> [a], returns some sensible default if possible, [] in the case of tail.

Comment by https://www.google.com/accounts/o8/id?id=AItOawnq-RfkVpFN15SWvQ2lpSGAi0XpNQuLxKM — Tue Jul 22 18:11:47 2025
Comments on this page are closed.