first version upgrade

[devspec.git] / devspec.en_US / 3.2.name-style.txt

\r
\r
# introduction\r
==============\r
\r
    in a program, src-code is consisted by lots of symbol word. some of them \r
are fixed, and called reserved-words. some of them is a chars beyound a-z and \r
A-Z and 0-9 and _, called operation-char. some of them are normal word for\r
programming element, variables, functions, types, macros, and so on.\r
        this doc is used to describe the guide for the third part above.\r
        a clear and better name is helpfull in program coding and reading. name is \r
a interface between different program, and different developers.\r
\r
        there is a tool to descript words charactors, it is regular-expression. it \r
can be used to describe the name in program.\r
\r
    a word consisted by a format, can express more informations.\r
        eg: a variable name called 'i32TempValue', can be dispatched by those info:\r
\r
@ i, integer, the type of this variable.\r
@ 32, bit lenth, the size of this variable.\r
@ Temp, short name of 'temperature'. with a four char short name to express a \r
  long word.\r
@ Value, the word it self.\r
\r
    name style defines format like the above example. it's helpfull for a \r
developer to known the meaning of a variable.\r
\r
    in current world, there is more coding-style in various program guide. this\r
doc is a general doc for name style.\r
\r
    name style is used for program element, and also used for file name.\r
\r
\r
\r
# conception\r
============\r
\r
    those conception are used for general text.\r
\r
@ char-encoding-set: a charactor is described as a binary code in computer\r
  system. the traditional char-encoding-set is asdii, and the popular one is \r
  utf-8. a program src-code use ascii as normal. if a compiler support multi-\r
  bytes encoding, such as utf-8, normally it is used for string data in \r
  program. the code it self is writen by ascii in most of program language.\r
@ char/charactor: one charactor in various char-encoding-set. it's one byte\r
  size data in ascii, and it's two bytes size data in GBK, and it's two or \r
  three bytes size data in utf-8.\r
@ word: it is consisted by a-z or A-Z or 0-9. in reg-expr, the char in the word\r
  has a name called 'alnum'.\r
@ words: it is consisted by several word. if it is used for language txt, it's\r
  a sentence.\r
@ opr-char: operation char, signatures. it is a char beyound word in ascii. \r
  there is a name in reg-expr for it, it called 'punct'.\r
\r
    general name for chars:\r
\r
@ upper-char: the char of A-Z.\r
@ lower-char: the char of a-z.\r
\r
    and those conception are used for programming.\r
\r
@ var-name/vname: variable name is a word for program variable or function \r
  name. it is consisted by word or '_', the first char of a word can not be\r
  digital char.\r
@ symbol/symbol-word: it's an alias for variable or function name. the \r
  importance of this name is pay attension on export or import in a program.\r
@ reserved-word/key-word: the fixed name used in code for a type of program\r
  language.\r
@ lexuary: a rule used to consist a word.\r
@ grammar: a rule used to orgnize different word with a txt syntax.\r
\r
    general reg-expr. it is used in reg-expr, and it is also a suitable name \r
for calling them.\r
\r
[:alpha:]: equal to [a-zA-Z]\r
[:lower:]: equal to [a-z]\r
[:upper:]: equal to [A-Z]\r
[:digit:]: equal to [0-9]\r
[:alnum:]: equal to [a-zA-Z0-9]\r
[:blank:]: matching ' '(blank), '\t'(table char)\r
[:space:]: matching ' '(blank), '\t'(table char), '\n'(newline), '\f'(),\r
           '\v'(vertical table char), '\r'(return char).\r
[:cntrl:]: control char. it is started from 000 to 037 and 177 (DEL) in ascii \r
           by oct.\r
[:print:]: equal to [:alnum:] and [:punct:] and ' '(blank).\r
[:graph:]: equal to [:alnum:] and [:punct:].\r
[:punct:]: it is: "`! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | \r
           } ~ '".\r
[:xdigit:]: chars for hex word. include 0-9 or A-F or a-f.\r
\r
\r
\r
# Popular Name Style\r
=====================\r
\r
    different developer has different code style. but in a orgnization, or in\r
a company, the name-style guide doc is needed by developers.\r
    the famous one is:\r
\r
@ GeneralStyle: a newer use single char or a single word to name the variable \r
  in normal. it's easy and readable in src-code. but there is a limitation in\r
  one word name to express the meaning of variable or function.\r
@ GNUStyle: join different word with '_', the word can be full name string, or\r
  a short name string. it's an improvement of GeneralStyle.\r
@ MFCStyle: widlly used coding-style, and to be a traditional one. many \r
  c/cpp developers started from this one.\r
    it uses a short or full word name string combination, and the first char of \r
  every word is a upper-char, others is lower-char. it has a type prefix for \r
  variables or types by short word name.\r
    short word name can save the char space in storage. but sometimes, it is \r
  a bit hard to read the meaning of variable. i think it is usefull for low-\r
  level programming, because of less ram space cost.\r
@ JavaStyle: it's a bit different with MFCStyle. the first word in name string \r
  is started with lower-char. this featrue is compative with one word name. \r
  the name of variable is consisted without type prefix, except the type name \r
  of a class.\r
\r
    here enum the example of different coding-style for c/cpp.\r
    GeneralStyle example:\r
\r
```\r
int i, j, value;\r
\r
int foo ()\r
{\r
        // replace code here.\r
        printf("value is : %d\n", value);\r
\r
        return 0;\r
}\r
```\r
    the name is very short, it's helpfull for code-reading, but weakness for \r
expression of meanings.\r
    others express a name with multi-word, maybe with a type prefix.\r
    it is not very nice for reading, if the lenth of name string is too long.\r
\r
    GNUStyle example:\r
\r
```\r
int i, j, value_for_test;\r
\r
int example_function ()\r
{\r
        // replace code here.\r
        printf("value is : %d\n", value_for_test);\r
\r
        return 0;\r
}\r
```\r
\r
    MFCStyle example:\r
\r
```\r
int i, j, i32ValueForTest;\r
\r
int ExampleFunc ()\r
{\r
        // replace code here.\r
        printf("value is : %d\n", i32ValueForTest);\r
\r
        return 0;\r
}\r
```\r
\r
    JavaStyle example:\r
\r
```\r
int i, j, valueForTest;\r
\r
int exampleFunction ()\r
{\r
        // replace code here.\r
        printf("value is : %d\n", valueForTest);\r
\r
        return 0;\r
}\r
```\r
\r
    those examples are simplly to show general difference between them. see\r
the corresponding documents for them to known them deeply.\r
\r
\r
\r
# subject in name style\r
=======================\r
\r
    a name style can be seperated by several parts. every part is a subject.\r
\r
@ short name or full name.\r
    a short name is a string that cost less space, it is helpfull for low-level \r
program.\r
\r
@ started with upper-char or join with '_'.\r
    the type of those two style can express the meaning of a name more better, \r
rather than a single word name.\r
    it is good for code reading when the name is too long.\r
    the after one cost a bit more char space in memory.\r
\r
@ started with lower-char for first word or not.\r
    by using lower-char for first word, it can be compative with GeneralStyle.\r
if the name is one word string, it's equal to GeneralStyle.\r
\r
@ type prefix.\r
    it's usefull for low-level programming, because developer use more basical\r
type variables in code, and it is helpfull to name a variable with type prefix.\r
    but in application programming, the developer face to many self-defined\r
type, or class type. the type prefix of a variable is normally a class-type \r
prefix, or other type-defined prefix.\r
\r
@ short name.\r
    how to get a readable short name?\r
    in MFCStyle, the short name is consisted by 2~6 chars. the char of a word \r
is the '¸¨Òô' char, or the first N char(4 char in traditional), so that it can \r
be recognized more better.\r
    in other condition, the name is described by several word, or a sentence,\r
the first char of this sentence also can be used for namming.\r
\r
\r
\r
\r
# Name Style\r
============\r
\r
    name style is used in those condition.\r
\r
@ program language element name. variables, functions, macros, types, and so \r
  on.\r
@ src code file.\r
@ src code pkg file.\r
@ binary install pkg file.\r
@ \r
\r
    if it is used for programming element, read the charpter of 'Name Style For \r
devrules'. if it is used for file name, read the charpter of 'Name Style for\r
file'.\r
\r
\r
\r
# Name Style For devspec\r
=========================\r
\r
    the style of name style is based on 'MFCStyle' for devspec. because it is\r
used for low-level system programming in most. the style used for application \r
developing is in extend document.\r
    the default name-style is GeneralStyle. it's easy for comprehansion. but\r
the interface(var/func) of a module, must use MFCStyle, and with extend specyfic below.\r
\r
    the helpfull features by MFCStyle are:\r
\r
@ using short name to save memory space, and easy to read.\r
@ using type prefix to known the type of symbol string.\r
@ it defined a lot of type prefix for variable. such as c(char), i(int), \r
  u(unsigned int), l(long), f(float), sz(string), lp(long pointer), v(void).\r
@ it uses 'C' for class type name as a type prefix. no prefix for others such\r
  as macro, enum, struct, union.\r
@ macro and enum define.\r
    use full upper-char with short name combination, and join word with '_'.\r
  append 'M_' prefix for macro, and 'EM_' for enum type.\r
    if the macro is defined as a macro-function, the name of it is same as\r
  function.\r
@ struct and union define\r
    all struct is defined as a typedef for global accessing. the default name\r
style is familiar with macro. using full upper-case with short name combination\r
and join with '_'. append 'ST_' prefix for struct, and 'UN_' for union, if it\r
is nessecory.\r
    the struct-type defined in struct is another name, which is different from\r
type name. use a '__tag_' prefix before type name.\r
    define a pointer type with 'P' prefix of the type. eg: \r
\r
```\r
struct __tag_ST_TYPE_EXAMPLE {\r
        int i;\r
} ST_TYPE_EXAMPLE, *PST_TYPE_EXAMPLE;\r
```\r
\r
@ \r
\r
\r
    the difference from MFCStyle is:\r
\r
@ use General Style for simple function feature implement.\r
@ type prefix extend: st(struct type), un(union type), em(enum).\r
@ size of type extend: 8/16/32/64.\r
@ type prefix for type name. is not only for class name, it uses type prefix \r
  for macro, enum, struct, union.\r
@ \r
\r
\r
\r
# General Style\r
===============\r
\r
@ single char variable\r
    the normal single char variable is:\r
# i, j, k, they are the default general purpose name.\r
# i, j, k; m, n, l; x, y, z; they are used for array index variable, or loop\r
  increasing variable.\r
# some variable is the short name of physical-unit or physical-value-name. eg:\r
  v(speed), t(time/temperature), s(distance).\r
\r
@ single word variable or function\r
    it's the first choosen of local variable in functions. and the function \r
name for traditional module.\r
    for example: traditional module of CStack, has many functions which is \r
single word name. push(), pop(), and so on. it's easy to use rather than \r
Multi-word. it has traditional operating function with a traditional name.\r
\r
@ \r
\r
\r
\r
\r
\r
\r
# syntax for file name\r
======================\r
\r
    see the charpter of 'pkg-file-name-format'.\r
\r
    file name style is used for those files:\r
\r
@ src code file.\r
    it's the similar with function name. it's consisted by upper-char started\r
word combination. and a type prefix such as C(Class), T(Type), M(Module).\r
\r
@ unit test src code file.\r
    the name of src code file, has a '_test' suffix after module name, and \r
before extend file name.\r
    eg: CStack.c is a src-code file for CStack module, and the test src file \r
for it is CStack_test.c.\r
\r
@ src code and binary install pkg file.\r
    it's a file name syntax, not file name style.\r
        the syntax of pkg file name is :\r
'<pkg-name>_[<pkg-type>-]<version>-<date>-<chksum>.<ext-name>'\r
\r
# pkg-name, main content. a pkg-name\r
# pkg-type, if it is a src pkg, append 'src' after pkg-name for src-pkg, leave\r
  it blank for binary-install-pkg, and 'res' for resource-install-pkg.\r
# version, a version code with three level version id.\r
# date, pkg archive date.\r
# chksum, 16bit hex summary of file content. it's used for file modification \r
  checking. or use 16bit hex summary of file sha1 value.\r
# ext-name, use tar.gz/tar.bz2/tar.xz for src-pkg, use 'etz' for install-pkg.\r
  \r
@ \r
\r
\r
\r
\r
\r
\r
\r
\r
\r
# Name Style\r
============\r
    ÔÚ³ÌÐòÖУ¬ÐèÒª¶Ô±äÁ¿¡¢º¯Êý¡¢ºê¶¨Òå¡¢ÎļþÃû½øÐÐÃüÃû¡£ÎªÁËʹÃû³Æ¿ÉÒÔÖ±¹ÛµÄ±íʾº¬Ò壬ÇÒÔÚʹÓÃÖмæ¹ËÊäÈëµÄ±ã½ÝÐÔ£¬ºÍ´úÂëµÄÃÀ¹Û£¬\r
¶ÔÃû³Æ×Ö·û´®µÄÃüÃûÒÔijÖÖ·ç¸ñºÍ¹æÔò½øÐÐÃüÃû£¬½«Õâ¸ö³Æ֮Ϊ³ÌÐòµÄÃüÃû¹æÔò/ÃüÃû·ç¸ñ\r
£¨NameSytle£©¡£\r
\r
        ʹÓô¿Ð¡Ð´»òMFCStyleµÄ´úÂë·ç¸ñ¡£\r
\r
    Ò»¸öÃû³Æ×Ö·û´®Óв»Í¬µÄµ¥´Ê»ò×Ö·û×é³É¡£\r
@ ÒÔµ¥´ÊÁ¬½ÓÃüÃû£¬Öм䲻´ø¿Õ¸ñ£¬Ê××Öĸ´óдÓÃÓÚÎĵµÖеÄÃèÊö£¬³ÌÐòµÄ±äÁ¿ºÍº¯ÊýÊ××ÖĸСд¡£\r
@ ÒÔµ¥´ÊµÄËõдÁ¬½Ó£¬ËõдΪ2-5¸ö×Öĸ£¬Ê××Öĸ´óд¡£\r
@ ʹÓõ¥´Ê¡¢Óï¾ä×éºÏµÄÊ××Öĸ×éºÏ£¬±íʾһ¸ö¹¦ÄÜÃû³ÆµÄËõд¡£\r
@ ÒÔµ¥´Ê¡¢Óï¾ä×éºÏµÄÊ××Öĸ×éºÏ£¬Ä©Î²»òÆðʼµÄµ¥´Ê²»ÊǷdz£³¤Ê±£¬ÒÔÍêÕûµÄµ¥´ÊÃüÃû£¬±È½ÏÈÝÒ×Á˽ⵥ´ÊµÄº¬Òå¡£eg£ºbuild-pkglist£¬\r
ËõдΪbpl£¬»òbuildpl£¬ÒÔÏÔʾbuildÕâ¸ö¹¦Äܵĺ¬Òå¡£\r
@ \r
\r
    ³£ÓõÄÃüÃû¹æÔò£º\r
@ ³ÌÐòÎļþÃû£ºÒÔ¶à¸ö´óд×Öĸ¿ªÍ·µÄµ¥´Ê±íʾ£¬Öм䲻¼Ó¿Õ¸ñ¡¢Ï»®ÏßµÈ×Ö·û¡£\r
@ ÀàÐÍÃû³Æ£º´óд×Öĸ¿ªÍ·µÄµ¥´Ê×éºÏ£¬²¢Ìí¼ÓÀàÐÍpfx¡£¶ÔÓÚtypedef structºÍtypedef enumµÄÀàÐͶ¨Ò壬ʹÓú궨Òå·ç¸ñµÄ´óд×Öĸ¼ÓÏ»®Ïß×éºÏ¡£\r
@ ±äÁ¿Ãû³Æ£ºµ¥¸öСд×Öĸ£¬»ò´¿Ð¡Ð´×ÖĸµÄµ¥¸öµ¥´Ê£¬»ò´óд×Öĸ¿ªÍ·µÄµ¥´Ê×éºÏ+ÀàÐÍpfx¡£¶ÔÓÚÀàÐÍpfx£¬ÓÃÓÚ±íʾ±äÁ¿ÀàÐ͵Äͬʱ£¬Çø·ÖÓÚº¯Êý¡£\r
@ ºê¶¨ÒåºÍö¾Ù/½á¹¹ÌåÀàÐÍÃüÃû£º´¿´óдµ¥´Ê×éºÏ£¬²¢ÒÔÏ»®ÏßÁ¬½Óµ¥´Ê¡£ºê¶¨ÒåÒÔM_Ϊpfx£¬½á¹¹ÌåÒÔST_Ϊpfx£¬Ã¶¾ÙÀàÐÍÒÔEM_Ϊpfx£¬ÁªºÏÀàÐÍ\r
ÒÔUN_Ϊpfx¡£\r
\r
    ¶ÔÓÚÃüÃûµÄ·½·¨£¬Í¨³£½¨ÒéÐÔµÄÕâôʹÓãº\r
@ ʹÓõ¥¸ö×Ö·ûµÄÁÙʱ±äÁ¿£¬i¡¢j¡¢x¡¢y¡¢z¡¢m¡¢n¡¢k¡¢lµÈ£¬ÓÃÓÚindex¡£ÆäËüµ¥¸ö×ÖĸµÄ±äÁ¿ÃüÃûÓÃÓÚÒ»¸öº¯ÊýÄÚµ¥¸öobjµÄ±íʾ¡£\r
@ 2¡«3¸ö×Ö·ûµÄËõд£¬»òÒ»¸öµ¥´Ê£¬ÓÃÓÚÒ»¸öº¯ÊýÄÚµ¥¸öobjµÄ±íʾ¡£\r
@ ÔÚº¯ÊýÖÐʹÓõıäÁ¿¶ÔÏó½Ï¶à£¬»ò±äÁ¿¶ÔÏó²»³£Óûò²»Í¨Óã¬ÐèʹÓÃÍêÕûµÄÃû³Æ×Ö·û´®£¬Ê¹±äÁ¿µÄº¬Òå±È½ÏÖ±¹Û¡£\r
@ ³ÉÔ±±äÁ¿£¬ÓÈÆäÊÇpublicʹÓõģ¬Ê¹ÓÃMFCStyle£¬ÇÒÌí¼ÓÀàÐÍpfx¡£\r
@ ³ÉÔ±º¯ÊýÒÔµ¥¸öµ¥´Ê±íʾµÄ£¬Ê¹Óô¿Ð¡Ð´Ãû³Æ£¬»ò´óдÆðʼµÄ×Ö·û´®ÃüÃû£¬¸ù¾ÝʹÓÃÏ°¹ß¶ø¶¨¡£ÀýÈçÒ»¸ö¶ÓÁÐQueueÊÇͨÓÃÀàÐÍ£¬ÔÚ¶¨Òå³É±äÁ¿Ê¹ÓÃ\r
ʱºÜ¶àʱºò¿ÉÄÜʹÓõ¥¸öСд×Öĸ£¬»ò´¿Ð¡Ð´µ¥´Ê£¬ËùÒÔµ¥¸öµ¥´ÊµÄ³ÉÔ±º¯ÊýʹÓô¿Ð¡Ð´£¬ÇÒ¾¡Á¿Ê¹Óõ¥¸öµ¥´Ê±íʾһ¸ö³ÉÔ±º¯Êý¡£\r
@ ¾Ö²¿±äÁ¿Í¨³£Ê¹Óõ¥¸öСд×Öĸ£¬´¿Ð¡Ð´Ëõд»ò´¿Ð¡Ð´µ¥´Ê£¬ÒÔʹ´úÂë¿´ÉÏÈ¥¾¡Á¿¼ò½à¡£\r
@ ¶ÔÓÚpublicµÄÈ«¾Ö±äÁ¿£¬Ê¹Óôóд×Öĸ¿ªÍ·µÄµ¥´Ê×éºÏ£¬²¢´øÀàÐÍpfx¡£\r
@ ¶ÔÓÚ¾Ö²¿±äÁ¿Öв»³£ÓõıäÁ¿ÀàÐÍ»ò±äÁ¿ÄÚÈÝ£¬ÐèÒªÒÔ¶à¸öµ¥´Ê±íʾµÄ£¬²Î¿¼publicµÄÈ«¾Ö±äÁ¿µÄÃüÃû¡£\r
\r
    GNUStyleµÄ±äÁ¿ÃüÃû£¬ÔÚ²ÎÊýÅäÖÃÎļþÖÐʹÓá£Ò»¸öÈ«¾ÖµÄ»·¾³±äÁ¿£¬Ê¹ÓÃgnuµÄstyle±È½ÏºÏÊÊ¡£\r
\r
\r
@ ±äÁ¿µÄ¶¨Òå\r
# ÔÚsrcµÄ¿ªÊ¼²¿·Ö¶¨Ò壬ÔÚÖ®ºóʹÓ᣷DZäÁ¿¶¨ÒåÇøÓò¶¨ÒåµÄ±äÁ¿£¬Í¨³£²»ÕâôʹÓ㬻òÓÃÓÚµ÷ÊԵȡ£\r
# ±äÁ¿¶¨ÒåÇøÓò²Î¿¼code-sample\r
# ±äÁ¿ÒÔÏÔʽµÄ±äÁ¿¶¨Ò壬²»¶¨ÒåÒþʽµÄ±äÁ¿ÉùÃ÷¡£\r
\r
@ \r