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 "keyword"), 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. "type" 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.