path: root/notes/naming_conv.txt

Naming convention
-----------------

1. For integer index variables, use i,j,k, if they don't need a more
   explanatory name (more explanatory names may be needed when indexes
   in different arrays are used).
2. For variables in common algorithms, consider using the standard names
   (typically single letter), unless those names are confusing.
2. When there is a standard abbreviated name, use it (see list below).
3. When the name can be abbreviated in a way that the meaning can be
   easilly guessed from the abbreviation, do abbreviate it
4. Use lowercase, unless a domain specific convention says otherwise
   (e.g. "E" for energy in some physics software)
4. For merging together word:
   - always use an underscore to merge a namespace word (e.g. library name)
     with function/variable names. For example:
     "mtx_new" in a library for linear algebra, or
     "ui_window_show" in a UI library.
   - when words are part of the same "namespace word", try to join them
     without an underscore, if they are short and the word is still easy
     to read. Otherwise, use an underscore. For example:
     "trans_funcdef"
     "printcol"
     "create_window"


Finally, when a name consists of multiple words/parts, do follow the
rules above for each part also.

Standard abbreviations
----------------------
Verb abbreviations may also be used for nouns,
e.g. cmp (for "compare") may be used for "comparison"
and iter (for "iterate") may be used for "iterator".

Abbreviations may also be joined with other words/prefixes/etc,
like "undef", "inaddr", "sigalg", "argp", etc.

Longer abbreviations (or full words, if short) are recommended for function
names (e.g. "config"), and shorter ones for parameters and local variables
(e.g. "cfg") when the meaning is obvious from the context.

Abbreviation should not be used completely out of place, for example, "cos"
should perhaps not be used in a webserver, instead one should spell out
"cosine" instead. Likewise, one should probably not use "vm" in a math
library.

The advantages of abbreviating often and standardizing abbreviations are:
* Easier to visually find a certain word.
* The algorithms/logic stand out more (and becomes easier to read), rather than the names.
* Identifiers are often used many many times, so it avoids repetition.
* If everyone agrees on abbreviations, then abbreviations only need to be
  learned once (and many should be obvious even first time).

    abs     absolute
    acct    account
    addr    address
    alg,algo algorithm (use "algo" when there could be confusion with "Application Layer Gateway")
    alloc   allocate
    arch    architecture (usually about CPU architecture)
    arg     argument
    arr     array
    asc     ascending
    async   asynchronous
    attr    attribute
    avail   available
    auth    authorization and authentication (when referring to both)
    authn   authentication
    authz   authorization
    auto    automatic
    aux     auxillary
    b       byte
    bg      background
    bin     binary
    bool    boolean
    bp      byte pointer
    brk     break
    btn     button
    buff    buffer
    calc    calculate
    ch      character
    chk     check
    chksum  checksum (or should it be "cksum"?)
    cert    certificate
    cfg,conf,config configure
    cli     command line interface
    clk     clock
    cmd     command
    cmp     compare
    cnt     count
    col     column
    cond    condition, conditional
    conn    connection
    const   constant
    conv    convert
    cos     cosine
    crypt   cryptography
    ctl     control
    ctx     context
    cur     current, cursor (should "cur" for "current" be spelled with two r's?)
    cust    custom
    db      database
    dbg     debug
    dec     decimal
    decl    declare
    def     define, default
    dep     depend
    desc    descending
    dev     device
    desc    describtion, descriptor
    dest,dst destintion (use "dst" for visual alignment with "src")
    dir     directory, direction
    div     divide
    dlg     dialog
    dload   download
    drv     drive
    dup     duplicate
    dyn     dynamic
    elem    element
    emu     emulate
    enc     encode
    env     environment
    eq      equal
    err     error
    esc     escape
    exec    execute
    expr    expression
    ext     external
    fd      file descriptor
    fg      foreground
    fmt     format
    fnp     function pointer
    frag    fragment
    fs      file system
    func,fn function
    fw      firmware
    fx      effects (used as a suffix, e.g. soundfx)
    gen     generate
    h       height (mainly when used together with x and y)
    hex     hexadecimal
    hdr     header
    hist    history, histogram
    horiz   horizontal
    hw      hardware
    id      ID, identifier (when mainly used as a key for lookups, typically not user-friendly)
    ident   identifier (when it is a name, not necessarilly unique)
    idx     index (but use i,j,k for index variables)
    if      network interface
    iface   interface (in other contexts than "network interfaces")
    img     image
    impl    implementation
    info    information
    init    initialize
    int     integer
    intern  internal
    intl    internationalization
    intro   introduction
    io      input/output
    iter    iterate
    kbd     keyboard
    lang    language
    len     length
    lib     library
    mach    machine
    max     maximum
    mech    mechanism
    mem     memory
    mgr     manager
    min     minimum
    misc    miscellaneous
    mk      make
    mod     module, modulus
    msec    milliseconds
    msg     message
    mtx     matrix
    mul     multiply
    neg     negative
    neq     not equal
    net     network
    nsec    nanoseconds
    num     number
    obj     object
    offs    offset
    ok      okay
    op      operation, operator
    opt     optional, option
    os,opsys operating system
    p,ptr   pointer
    param,prm parameter
    paren   parenthesis
    passwd  password
    perf    performance
    perm    permissions
    pg      page
    phys    physical
    pict    picture
    pkg     package
    pkt     packet
    pos     position
    pref    preference
    pres    presentation
    prev    previous
    priv    private
    proc    process
    prog    program
    prop    property
    proto   protocol
    pub     public
    pwr     power
    qual    qualifier, quality (FIXME overlap)
    recv    receive
    ref     reference
    reg     register, registry
    regex   regular expression
    reloc   relocate
    repo    repository
    repro   reproduce
    req     request, require (FIXME overlap)
    resp    response
    ret     return value, return
    s       string (in variable names)
    sp      space
    sec     security
    sep     separator
    seq     sequence
    sess    session
    sig     signature, signal (FIXME overlap)
    sin     sinus
    snd     sound
    sock    socket
    spec    specify, special
    sqrt    square root
    src     source
    srv     server
    std     standard
    str     string (in function names)
    surf    surface
    sub     subtract
    svc     service
    sw      software
    sym     symbol
    sync    synchronize, synchronous
    sys     system
    tan     tangens
    tbl     table
    term    terminal, terminate
    tmp     temporary
    tok     token
    trans   translate
    trunc   truncate
    txt     text
    ui      user interface
    uid     user id
    uniq    unique
    upd     update
    util    utility
    val     value
    var     variable
    vec     vector
    ver     version
    vert    vertical
    vfy     verify
    virt    virtual
    vm      virtual memory, virtual machine
    w       width (mainly when used together with x and y)
    warn    warning
    win     window

More suggested abbreviations
----------------------------
    
The following abbreviations are *examples* of what can be abbreviated when
the meaning is obvious given the context (for example "kw" in a parser can
be taken to mean "kwa"), or if the identifier is used often enough
to motivate a shorter name (in which case the meaning should be documented)

    act     active
    adj     adjust
    adv     advanced
    aud     audio
    bk      back
    blk     block
    cal     calendar
    ch      change
    cls     class
    con     console
    ctr     center
    d       day
    dec     decrement, decimal
    del     delete
    det     detect, determinant
    dig     digit
    dl      download
    dpy     display
    ent     entry
    eqn     equation
    evt     event
    fact    factory
    flg     flag
    h       hour
    hi      high
    ign     ignore
    inc     increment, include
    ins     insert
    inst    install, instance
    kw      keyword
    ld      load
    ldr     loader
    lic     license
    lk      lock
    ln,lnk  link ("lnk" avoids ambuigity with natural logarithm "ln")
    lo      low
    loc     location
    lyt     layout
    m       minute, month    
    mid     middle
    min     minute (also minimum)
    mo      month
    mus     music
    mv      move
    ovl     overlay
    pal     palette
    pct     percent
    pol     policy
    pts     points
    rd,r    read
    rel     relative
    rem     remainder
    rev     reverse
    rm      remove
    rnd,rand random
    sb      string buffer
    sct     section
    sec     second
    sel     selection
    sema    semaphore
    shl     shift left
    shr     shift right
    sk,st   stack (FIXME which one to use?)
    stmt    statement
    stor    storage
    succ    successor
    ul      upload
    un      unary (when used as a prefix, e.g. unop/binop for unary/binary operators)
    vel     velocity
    vid     video
    vol     volume
    w,wk    week
    wr,w    write
    wm      window manager
    y,yr    year
    z       prefix for anything compressed

In general, when creating abbreviations, follow these rules:

1. Try to visually align related variables (e.g. "src" and "dst")
2. Prefer established abbreviations over new ones (e.g. "auto" rather than "aut", but see rule 4).
3. Do not abbreviate short names (e.g. don't shorten "abort" to "abrt"),
   except if the long name is a keyword (e.g. "kwb" to "typ")
4. The abbreviation should start with the first letter in the word
5. Prefixes like "pre, "post", "ex", "un" should not be abbreviated
   (if saving one letter is important, then "ex" can be shortened to "x").
6. Do not include letters in "grammar suffixes" like "-ion" in "configuration"
7. In general, the abbreviation should have one of these forms:
    - The first syllable in the word. Do NOT remove double consonants
      at the end, unless the word is also written with a single consonant
      in some cases, for example:
       - "mid" from "middle" ("mid" is used in "midwinter").
       - "diff" from "difference"
       - "buff" from "buffer"
       (note that in the latter two cases there is no related word
        with only a single "f").
    - Include the most pronounced syllables or most uncommon letters
      (like "q", "x", "y", "z" etc).
      E.g. "stmt" for "statement". If there are too many syllables for
      the purpose (more common identifiers can have shorter names),
      skip common syllables (like n,t,r,s) at the end.
8. For plural there should be a "s" at the end.