Conventions.txt

Key bindings
============

If a key is appropriate, language grammars should have ctrl-shift-option as modifier, and the first letter of the language name as key.

Other bundle items should generally have ctrl-shift as modifier.

These keys are often specialized for a language:

    command-B          --  build
    command-R          --  run
    ctrl-H             --  lookup current word/selection in the documentation
    ctrl-shift-V       --  validate (show syntactical errors)
    ctrl-shift-W       --  wrap selection (e.g. in begin/end tags for HTML)
    shift-return       --  create a function/method body with previous word as name
    ctrl-return        --  insert a “descriptive” return (e.g. \n in strings, <br> in HTML)
    cmd-return         --  move to end of line and insert a newline (this is not specialized)
    cmd-option-return  --  move to end of line and insert potential end-of-line symbol (; in many sources, . in prose)
    cmd-shift-return   --  as cmd-option-return, but also insert a newline
    enter              --  insert a newline and start a new “item” (e.g. line comment, bullet point, etc.)

Naming Bundle Items
===================

Bundle items should use Title Case.

Avoid repeating the name of the bundle in the command name. For example under Ruby we have Run Script and not Run Ruby Script and under Xcode we have Build, not Build Xcode Project, etc.

Be concise in the name, i.e. make it evident what the command does without writing a page full of information. Refrain from using abbreviations.

Snippets
========

Use tabs instead of spaces in snippets (if the user uses spaces as tabs, TM will convert the snippet when inserted).

Generally fill in default text in placeholders. This is a cue both to where the placeholders (tab stops) are, and what value they're likely to take.

Name the snippet after what it inserts, using “..” for placeholders and put the (potential) tab-trigger in parentheses. If it inserts a lot, either name it after the start of what's inserted, or find a descriptive name for what it inserts.

Choose a tab-trigger which you can remember in half a year. I.e. normally use the first word of what's being inserted instead of an abbreviation. This will make it easier to remember, and it also allows expansion even if the user started to type the actual construct, before remembering the snippet.

Language grammars
=================

When you put comments in these, please add your name if it's stating a problem, asking a question etc.