ax_editing_notes

Ignored

All Examples: Editing Notes

In order to maintain consistency and readability, I've imposed some editing conventions. These cover formatting of example code, organization of pages and sections, etc.

Before you start creating (or even editing) pages, please take a few minutes to review these notes. This will reduce the likelihood of rejection and (ultimately) result in better results.

Example Page Organization

Each example page describes a problem and a suggested solution. For regularity, pages are divided into several sections (Problem, Solution, Discussion, and See Also). Additional sections may be added if need be, but sub-sections are preferred.

Problem

The Problem section contains a brief description of a problem (ie, use case). This should be couched in the user's terms, avoiding implementation issues.

Solution

The Solution section should contain example code and explanatory notes.

Discussion

The Discussion section should contain comments, notes, warnings, etc.

Example Section - Details

Example code should be easy and (if possible) pleasant to read and comprehend. The difficult parts (if any) should have to do with the logic, not the format. So, even if you prefer a terser style for your own code, don't use it here.

Comments

Comments should not simply echo (ie, transliterate) the code. Rather, they should explain the code's purpose, plan, etc.

In queries and rules, comments can be used to provide a plausible narrative. Although Datalog clauses are not evaluated in order, it can be useful to explain how the programmer "thinks" they work.

Docstrings

Docstrings (documentation strings) are an important part of Clojure, providing useful information in the code base and at runtime (eg, in a REPL). Try to create a short but descriptive docstring for every Clojure function. Typically, this will expand on and clarify the function name.

Name Selection

Name selection is a difficult problem. Short names are concise, but lack clarity and mnemonic value. Long names are easy to read and understand, but bulk up the code. The key to the trade-off is to think about the name's scope.

Function names have substantial scope (ie, they can be used anywhere), so they can be fairly long (eg, find-commits-for-fn). On the other hand, try not to go crazy (:-).

Variable and symbol names (eg, foo, :foo, ?foo) are used locally, so they can and should be shorter. However, they makes it more challenging to create mnemonic names. Remember, we don't want to waste the readers' time by making them guess at the meaning of cryptic names.

In general, try to keep local names between three and ten characters. Replace single-character names (eg, ?c) with words or word pairs (eg, ?commit, ?code_src). Use dashes or underscores to separate the words.

Spacing

Indentation and in-line spacing should be used to clarify structure, emphasize parallelism, and make key content "stand out". For example, it's useful to line up brackets and parentheses. Query clauses, in particular, should be presented in tabular form, allowing the reader to scan down columns of attributes, values, etc.

Blank lines can be used to delimit sections and provide "breathing room". If more room is needed (eg, for extended comments or notes), feel free to break up the code display to interpose paragraph-formatted text.

Miscellany

Links

To make the wiki page's source code a bit easier to read, links should use Markdown's reference links. The link definitions should be collected at the top of the page.

For an example, see the beginning of the source code for this page.

Page Headings

GitHub's wiki engine has some peculiar "features" regarding page headings:

It uses (a modified form of) the page name as the initial H1 heading.
It ignores the first (explicit) H1 heading.
It ignores content-free H1 headings (eg, #).

I don't like this behavior, but there is only so much I can do about it. For example, I simply have to live with the generated H1 heading. However, I can (and do) add my own H1 heading below it, preceded by one (eg, # Ignored) for the gremlins to eat, eg:

# Ignored
# Query Example: `commit-dates`