hledger/doc/CODE.md

Code

hledger is a suite of applications, tools and libraries. The main hledger code repository is github.com/simonmichael/hledger (shortcut url code.hledger.org). There are also various hledger add-ons maintained as separate projects with their own repos.

hledger packages

Within the main repo, there are a number of separate cabal packages, making it easier to pick and choose parts of hledger to install or to package. They are:

hledger-lib

package, code

Core data models, parsing, standard reports, and utilities. Most data types are defined in Hledger.Data.Types, while functions that operate on them are defined in Hledger.Data.TYPENAME. Under Hledger.Read are parsers for the supported input formats. Data files are parsed into a Journal, which contains a list of Transactions, each containing multiple Postings of some MixedAmount (multiple single-CommoditySymbol Amounts) to some AccountName. When needed, the Journal is further processed to derive a Ledger, which contains summed Accounts. In Hledger.Reports there are standard reports, which extract useful data from the Journal or Ledger.

Here's a diagram of the main data model:

hledger

package, code, manual

hledger's command line interface, and command line options and utilities for other hledger tools.

Try tracing the execution of a hledger command:

1. Hledger.Cli.Main:main parses the command line to select a command, then
2. gives it to Hledger.Cli.Utils:withJournalDo, which runs it after doing all the initial parsing.
3. Parsing code is under hledger-lib:Hledger.Read, eg Hledger.Read.JournalReader.
4. Commands extract useful information from the parsed data model using hledger-lib:Hledger.Reports, and
5. render in plain text for console output (or another output format, like CSV).
6. Everything uses the data types and utilities from hledger-lib:Hledger.Data and hledger-lib:Hledger.Utils.

hledger-ui

package, code, manual

A terminal interface.

hledger-web

package, code, manual

A web interface. hledger-web starts a web server built with the yesod framework, and (by default) opens a web browser view on it. It reads the journal file(s) at startup and again whenever they change. It can also write (append) new transactions to the journal file.

There are two main views, which can be filtered with queries:

• /journal, showing general journal entries (like hledger print)

• /register, showing transactions affecting an account (slightly different from hledger's register command, which shows postings).

There is also:

• a sidebar (toggled by pressing s) showing the chart of accounts (like hledger balance)
• an add form for adding new transactions (press a)
• a help dialog showing quick help and keybindings (press h or click ?)

Most of the action is in

• config/routes
• templates/default-layout-wrapper.hamlet
• Foundation
• Handler.*
• static/hledger.js
• static/hledger.css

Handler module and function names end with R, like the yesod-generated route type they deal with.

Dynamically generated page content is mostly inline hamlet. Lucius/Julius files and widgets generally are not used, except for the default layout.

Here are some ways to run it during development:

• yesod devel: runs in developer mode, rebuilds automatically when config, template, static or haskell files change (but only files in the hledger-web package):

$ (cd hledger-web; yesod devel)

• yesod-fast-devel may be a good alternative, also reloads the browser page

• stack ghci: runs the server in developer mode from GHCI. Changes to static files like hledger.js will be visible on page reload; to see other changes, restart it as shown.

$ (cd hledger-web; stack ghci hledger-web)
hledger-web> :main --serve   # restart: ctrl-c, :r, enter, ctrl-p, ctrl-p, enter

• just ghci-web: runs the server in developer mode from GHCI, also interprets the hledger-lib and hledger packages so that :reload picks up changes in those packages too:

$ just ghci-web
ghci> :main --serve

(This rule also creates symbolic links to hledger-web's config, messages, static and templates directories, needed in developer mode, so it can run from the top directory. This may not work on Windows.)

Quality

Relevant tools include:

• unit tests
• functional tests
• performance tests
• documentation tests
• ui tests (manual)
• installation tests
• code reviews

Code review

• Code review party 2014/7/21-25: discussion
• Dev sprint/party 2015/10/10: discussion

Code docs

Haddock comments are the standard way of attaching docs (and sometimes small tests) to a haskell definition. They are used pervasively in the hledger codebase.

From #2222:

I tend to add a line of english description to most things. They can be a big help to someone else debugging/improving code later.

I use Haddock but I do not like to tell obvious things in Haddock comments. (And if there are surprising things I try to eliminate the surprises instead.)

I hear you! This is of course a recurring debate among programmers.

I agree that obviously redundant haddocks that add no value are to be avoided.

In the hledger codebase, there's no hard requirement for haddocks. And sometimes the bar can be lower, eg in single-purpose less-frequently-developed modules like FODS.hs.

But I believe it's always worth at least considering them when adding code, and it's something I consider when reviewing code. I'll give some reasons why I think so, for the record (and maybe they'll persuade you just a little).

Haddocks help guide and anchor the developer while writing or changing code. They are the cheapest kind of doc, spec and test suite. They also create a place to add actual doctests, now or later.

Haddocks can be helpful to contributors who are not expert haskellers, which happens quite often in the hledger project. The human language descriptions can complement the code, reducing cognitive effort and helping with mental chunking. I think people find the hledger's code, with its pervasive haddocks, above average in readability. (And I think we've had more successful contributions as a result.)

Haddocks can also help experienced developers move faster. Code which seems quite clear and obvious when you are writing it is often less obvious to oneself a few weeks or years later. And certainly it can be less obvious to others than we might think. When debugging or coding we are often mentally stretched and we would prefer to conserve brainpower for the main task.

In my experience debugging/writing/changing hledger code,

• Number of times I've regretted seeing a haddock comment attached to some code: almost zero.
• Effort to remove an excessive haddock: almost zero.
• Number of times I've been trying to understand some contributed code and haddocks would have saved my time: quite a few.
• Number of times I've appreciated code haddocks and found them helpful: many.
• Number of times I've found errors or staleness in haddocks: not often.
• Effort to fix wrong haddocks, or to write new ones: usually very low. And if it's high, it's usually very worthwhile because it alerts me to a confusion in the code or clarifies my thinking.

hledger is a documentation-driven project, with docs in general being a top priority. I think this is one reason it has held together and kept improving over a long period.