pdf
|<<
<
>
>>|
/
The Art of Naming ---- The Art of {{#x|Naming}} {{#x|命名}}的艺术 ☺{{#author|agentzh (章亦春)}}☺ {{#date|2006.9}} ---- Why naming {{#ci|matters}}? 为什么命名很{{#ci|重要}}? ---- {{#ci|Good}} hackers ➥ {{#x|poets}} and {{#x|wordsmiths}} 好的黑客 ➥ 诗人和词汇大师 ---- A {{#ci|poetry}} in Pugs' {{#x|Main.hs}} {{#tag|⇒}} Pugs 的 Main.hs 中的英文诗歌 {{#tag|⇒}} ---- A {{#ci|ship}} then new they built for {{#ci|him}} Of {{#x|mithril}} and of {{#x|elven-glass}} With shining prow; no shaven oar Nor sail {{#ci|she}} bore on silver mast; The Silmaril as {{#x|lantern light}} And banner bright with {{#x|living flame}} To gleam thereon by Elbereth {{#ci|Herself}} was set, who thither came... ---- 众人为彼造新舟, 铸以秘银精灵璃。 船首闪耀何需桨, 银桅未有风帆系。 无双宝钻作灯炬, 旗帜辉煌展生焰。 映照燃星雅碧绿, 神祇乘梭下九天。 -- {{#t|唐凤}} ---- Perl 6 {{#ci|translation}} ⇒ {{#x|翻译}}到 Perl 6 编程语言 ⇒ ---- {{#kw|use v6}}; {{#kw|for}} {{#v|$*Larry}} { {{#kw|our}} Ship {{#v|$pugs}} .= {{#kw|new}}(:of{{#x|<mithril elven-glass>}}); {{#kw|given}} {{#v|$pugs}} { {{#v|$.prow}} {{#kw|does}} Shine; Silver {{#v|$.mast}} {{#kw|but none}}(Oar::Shaven, Sail); Light {{#v|$.lantern}} := {{#v|$*Silmaril}}; Bright {{#v|$.banner}} := Flame.bless:{}; {{#kw|when}} {{#v|$*Elbereth}}.gleam { .sail(...); } } } ---- {{#ci|Top}} programmers take {{#x|naming}} issues very seriously 顶级的程序员对命名问题 非常认真。 ---- as seen on the {{#ci|#perl6}} channel of {{#x|irc.freenode.net}}... 正如在 irc.freenode.net 上的 #perl6 通道里 所看见的那样…… ---- {{img src="#" width="0" height="0"}} {{img src="images/larry.jpg" width="240" height="392"}} ---- {{#v|<agentzh>}} TimToady++ # JIT syn fixes {{#v|<TimToady>}} thanks {{#v|<TimToady>}} I looked at {{#ci|several hundred}} words before picking START. {{#v|<章亦春>}} (Larry Wall)++ # 即时 Perl 6 文档修改 {{#v|<Larry Wall>}} 谢谢 {{#v|<Larry Wall>}} 我在挑选出 START 这个名字之前查看了 {{#ci|几百个}}单词。 ---- {{img src="images/audrey.jpg" width="480" height="403"}} ---- {{#v|<gaal>}} defer? slothlike {{#v|<audreyt>}} I like \"defer\" {{#v|<audreyt>}} gaal++ * audreyt deletes Data::Thunk and uploads Data::Defer {{#v|<audreyt>}} ...and it's now Scalar::Defer {{#v|<audreyt>}} {{#ci|naming}} takes {{#ci|more}} time than tests+doc+code {{#v|<高浪>}} defer 怎么样? 有些惰性的味道 {{#v|<唐凤>}} 我喜欢“defer” {{#v|<唐凤>}} 高浪++ * 唐凤删除了 Data::Thunk 并上传了 Data::Defer {{#v|<唐凤>}} ……现在它叫做 Scalar::Defer 了 {{#v|<唐凤>}} {{#ci|命名}}所花费的时间比测试 + 文档 + 实现代码{{#ci|还要多}} ---- {{#tag|☆}} Follow the {{#x|naming convention}} of the language {{#ci|you}} are using and try to be consistent. 遵循你所使用的语言的命名约定, 并努力保持一致性。 ---- The problem with being {{#x|consistent}} is that there are {{#ci|lots}} of ways to be consistent, and they're all {{#x|inconsistent}} with each other. -- {{#t|Larry Wall}} 保持一致性的困难在于存在许许多多种不同方式 来实现一致性,而且它们彼此之间都是不一致的。 -- {{#t|Larry Wall}} ---- {{#v|// C++ STL naming style}} {{#x|vector}}<{{#x|string}}> list; list.{{#ci|push_back}}(\"hello\"); while (!list.{{#ci|empty}}()) {...} ---- {{#v|// Java naming style}} {{#x|List}} list = new {{#x|ArrayList}}(); list.{{#ci|add}}(\"hello\"); while (!list.{{#ci|isEmpty}}()) {...} ---- {{#v|// C# naming style}} {{#x|ArrayList}} myAL = new {{#x|ArrayList}}(); myAL.{{#ci|Add}}(\"hello\"); Console.{{#ci|WriteLine}}(myAL.{{#ci|ToString}}()); ---- {{#tag|☆}} Use {{#ci|meaningful}} names 使用{{#ci|有意义}}的名字 ---- {{#ci|?}} Button {{#x|button1}} = new Button(\"New\"); {{#ci|?}} Button {{#x|button2}} = new Button(\"Open\"); {{#ci|?}} Button {{#x|button3}} = new Button(\"Save\"); +{{#x|☹}} This is {{#ci|bad}}. ---- {{#ci|?}} Button {{#x|button_New}} = new Button(\"New\"); {{#ci|?}} Button {{#x|button_Open}} = new Button(\"Open\"); {{#ci|?}} Button {{#x|button_Save}} = new Button(\"Save\"); +{{#x|☹}} This is {{#ci|ugly}}. ---- Button {{#x|btnNew}} = new Button(\"New\"); Button {{#x|btnOpen}} = new Button(\"Open\"); Button {{#x|btnSave}} = new Button(\"Save\"); +{{#x|☺}} This is {{#ci|good}}. ---- The {{#x|Ugly}}, the {{#x|Bad}}, and the {{#x|Good}} 丑的,坏的,好的 ---- {{#tag|☆}} Choose {{#ci|nouns}} for your {{#x|class}} names 从名词中为你的类取名 ---- {{img src="images/noun.gif" width="288" height="266"}} ---- class {{#x|Evaluator}} { ... } class {{#x|Solver}} { ... } class {{#x|Withdrawal}} { ... } +{{#x|☺}} These are {{#ci|good}}. ---- {{#ci|?}} class {{#x|Evaluate}} { ... } {{#ci|?}} class {{#x|Solve}} { ... } {{#ci|?}} class {{#x|Withdraw}} { ... } +{{#x|☹}} These are {{#ci|bad}}. ---- {{#v|# The following class/module names are}} {{#v|# also good:}} {{#kw|package}} CGI::Simple; {{#kw|package}} XML::Smart; {{#kw|package}} Class::DBI::Sweet; {{#kw|package}} Test::Easy; ---- {{#tag|☆}} Choose active {{#ci|verbs}} for your {{#x|method}} names 从主动动词中为你的方法取名 ---- {{img src="images/verb.gif" width="437" height="224"}} ---- $dbh = DBI.{{#x|connect}}('dbi:odbc:qqbase'); $dbh.{{#x|commit}}(); $account.{{#x|update}}(balance => 100); +{{#x|☺}} These are {{#ci|good}}. ---- {{#ci|?}} $dbh = DBI.{{#x|connection}}('dbi:odbc:qqbase'); {{#ci|?}} $dbh.{{#x|committing}}(); {{#ci|?}} $account.{{#x|updated}}(balance => 100); +{{#x|☹}} These are {{#ci|bad}}. ---- {{#tag|☆}} Choose {{#ci|nouns}} or {{#ci|adjectives}} for your {{#x|property}} names 从名词或者形容词中为你的属性取名 ---- @list.{{#x|length}} $persion.{{#x|name}} {{#kw|if}} $dbh.{{#x|available}} { ... } {{#kw|die if}} $set.{{#x|is_empty}}; +{{#x|☺}} These are {{#ci|good}}. ---- {{#tag|☆}} Use {{#x|namespaces}} to split your {{#ci|verbose}} class names. 使用命名空间来分割你冗长的类名。 ---- {{#ci|?}} class {{#x|Makefile_Parser_AST_Element}} { {{#ci|?}} ... {{#ci|?}} } {{#ci|?}} {{#x|Makefile_Parser_AST_Element}} elem(); +{{#x|☹}} This is {{#ci|ugly}}. ---- namespace {{#x|Makefile::Parser::AST}} { class {{#x|Element}} { ... } } {{#x|Makefile::Parser::AST::Element}} elem(); +{{#x|☺}} This is {{#ci|good}}. ---- {{#tag|☆}} Use {{#x|short}} names for {{#ci|common}} things. 为常用的东西取短名字。 ---- {{#ci|Common}} operations should be \"{{#x|Huffman coded}}\". That is, frequently used operators should be {{#ci|shorter}} than infrequently used ones. -- {{#t|Larry Wall}} (Perl 6 Apocalypse 3) 对常见的操作应该进行“哈夫曼编码”。也就是说,频繁 使用的运算符的名称应该比那些不经常使用的要短。 -- {{#t|Larry Wall}} (Perl 6 启示录 3) ---- {{img src="images/huffman.gif" width="510" height="470"}} ---- {{#v|// The Java way:}} {{#ci|System.out.println}}(\"Computing the sum...\"); {{#kw|for}} ({{#kw|int}} i = 1; i <= n; i++) { sum += i; {{#ci|System.out.println}}(i); } {{#ci|System.out.println}}(\"Sum: \" + sum); +{{#x|☹}} This is {{#ci|ugly}}. ---- {{#v|# The Perl 6 way:}} {{#ci|say}} \"Computing the sum...\"; {{#kw|for}} 1..$n -> $i { $sum += $i; {{#ci|say}} $i; } {{#ci|say}} \"Sum: $sum\"; +{{#x|☺}} This is {{#ci|good}}. ---- {{#tag|☆}} Use {{#x|short}} names for {{#ci|locals}}. 为局部变量取短名字。 ---- {{#kw|int}} {{#ci|len}} = list.length; {{#kw|for}} ({{#kw|int}} {{#ci|i}} = 0; {{#ci|i}} < {{#ci|len}}; {{#ci|i}}++) System.out.println(list[{{#ci|i}}]); +{{#x|☺}} This is {{#ci|good}}. ---- {{#kw|int}} {{#ci|length}} = list.length; {{#kw|for}} ({{#kw|int}} {{#ci|index}} = 0; {{#ci|index}} < {{#ci|length}}; {{#ci|index}}++) System.out.println(list[{{#ci|index}}]); +{{#x|☺}} This is {{#ci|ugly}}. ---- {{#tag|☆}} Use {{#x|descriptive}} names for {{#ci|globals}}. (long names are okay.) 为全局结构取描述性的名字。 (长名字也可以。) ---- {{#ci|?}} {{#cm|# Globals in smartlinks.pl:}} {{#ci|?}} {{#kw|my}} (${{#x|count}}, ${{#x|broken_count}}); +{{#x|☹}} This is {{#ci|bad}}. ---- {{#cm|# Globals in smartlinks.pl:}} {{#kw|my}} (${{#x|link_count}}, ${{#x|broken_link_count}}); +{{#x|☺}} This is {{#ci|better}}. ---- {{#tag|☆}} Don't {{#ci|repeat}} yourself. (The {{#x|DRY}} principle) 不要重复你自己 (DRY 原则) ---- {{#ci|?}} {{#v|// The Java way:}} {{#ci|?}} {{#x|double}} value = {{#x|Double}}.parse{{#x|Double}}(\"3.14\"); +{{#x|☹}} This is {{#ci|ugly}}. ---- {{#v|// The C# way:}} {{#x|double}} value = {{#x|double}}.Parse(\"3.14\"); +{{#x|☹}} Just a bit better. ---- {{#v|// The Perl 6 way:}} {{#kw|my}} {{#x|Double}} $value = \"3.14\"; +{{#x|☺}} This is {{#ci|good}}! ---- {{#v|// The C/C++ way:}} {{#x|double}} value = atof(\"3.14\"); +{{#x|☺}} This is {{#ci|good}} too, though a bit fuzzy. ---- {{#ci|?}} {{#kw|class}} User{{#x|Queue}} { {{#ci|?}} {{#kw|int}} noOfItemsIn{{#x|Q}}; {{#ci|?}} {{#kw|int}} frontOfThe{{#x|Queue}}; {{#ci|?}} {{#kw|int}} {{#x|queue}}Capacity; {{#ci|?}} {{#kw|public int}} noOfUsersIn{{#x|Queue}}() { ... } {{#ci|?}} } +{{#x|☹}} This is {{#ci|ugly}}. ---- {{#kw|class}} User{{#x|Queue}} { {{#kw|int}} nitems; {{#kw|int}} front; {{#kw|int}} capacity; {{#kw|public int}} nusers() { ... } } +{{#x|☺}} This is {{#ci|good}}! ---- {{#tag|☆}} Tell me {{#ci|more}}! (Don't be {{#x|handwaving}}.) 多告诉我一些! (不要遮遮掩掩。) ---- {{#ci|?}} {{#kw|if}} ({{#x|check_even}}(num)) { ... } +{{#x|☹}} Check if it {{#ci|is}} an even number? +{{#x|☹}} Check if it {{#ci|is not}} an even number? ---- {{#kw|if}} ({{#x|is_even}}(num)) { ... } +{{#x|☺}} Now it is {{#ci|good}}! ---- {{#tag|☆}} Improper {{#x|abbreviations}} can be {{#ci|very confusing}}. 不恰当的缩写名可能会让人 非常迷糊。 ---- {{#v|<Sal>}} what is \"{{#x|JQL}}\"? {{#v|<clkao>}} {{#x|J}}abberwocky {{#x|Q}}uery {{#x|L}}anguage? {{#v|<TimToady>}} {{#x|J}}ust {{#x|Q}}uack {{#x|L}}oudly? {{#v|<audreyt>}} {{#x|J}}unctional {{#x|Q}}uantum {{#x|L}}ibrary? {{#v|<仲伟祥>}} 什么是“{{#x|JQL}}”? {{#v|<高嘉良>}} 废话查询语言? {{#v|<Larry Wall>}} 不过是高声吹嘘? {{#v|<唐凤>}} 联结性量子库? ---- {{#tag|☆}} {{#ci|Widely-used}} abbreviations are recommended. 提倡选择 广泛使用的缩写。 ---- {{#x|var}} ← variable {{#x|val}} ← value {{#x|init}} ← initialize / initialization {{#x|elem}} ← element {{#x|id}} ← identifier {{#x|len}} ← length {{#x|eval}} ← evaluate / evaluation {{#x|func}} ← function {{#x|sub}} ← subroutine {{#x|AST}} ← Abstract Syntax Tree ...{{#t|and many more}} ---- {{#tag|☆}} Chinese {{#x|Pinyin abbreviations}} can be {{#ci|extremely}} hateful. 汉语拼音缩写会非常令人讨厌。 ---- http://.../{{#x|xs}}_main.aspx?{{#x|xh}}=3030602110# http://.../{{#x|xscj}}_{{#x|gc}}.aspx?{{#x|xh}}=3030602110&{{#x|xm}}=章亦春 http://.../{{#x|xscxbm}}.aspx?{{#x|xh}}=3030602110&{{#x|xm}}=章亦春 +{{#ci|xs}} == 学生 (student) ? +{{#ci|xh}} == 学号 (student id) ? +{{#ci|xm}} == 姓名 (name) ? +{{#ci|xscj}} == 学生成绩 (student grades) ? +{{#ci|xscxbm}} == 学生重修报名 (XXX) ? +{{#ci|gc}} == {{#x|???}} ---- I'm a {{#x|Chinese}}, but I still find it {{#ci|hard}} to understand. 我是中国人, 但我发现理解它们仍然很困难。 ---- {{#tag|☆}} Avoid potential {{#ci|ambiguity}} and {{#ci|confusion}}. 避免可能的歧义和混淆。 ---- To get the number of elements in an array, use the {{#ci|.elems}} method. You can also ask for the total string length of an array's elements, in bytes, codepoints or graphemes, using these methods {{#ci|.bytes}}, {{#ci|.codes}} or {{#ci|.graphs}} respectively on the array. The same methods apply to strings as well. There is no {{#ci|.length}} method for either arrays or strings, because length does {{#ci|not}} specify a {{#x|unit}}. -- {{#i|Larry Wall}} (The Perl 6 Synopsis 2) ---- 想得到数组中的元素数目,可以使用 {{#ci|.elems}} 方法。 你也可以利用 {{#ci|.bytes}}、 {{#ci|.codes}} 或者 {{#ci|.graphs}} 分别 以字节、编码点、或者字形为单位来查询数组元素 的总长度。字符串也拥有这些方法。 对数组和字符串而言,都不再有 {{#ci|.length}} 方法了, 因为 length 并{{#ci|没有}}指明{{#x|长度单位}}。 -- {{#i|Larry Wall}} (Perl 6 纲要 2) ---- {{#tag|☆}} DWIM? Do what {{#ci|you}} mean! 言行一致! ---- {{#ci|?}} {{#kw|class}} Array { {{#ci|?}} {{#cm|// print out the contents:}} {{#ci|?}} {{#kw|public void}} {{#x|init}}() { {{#ci|?}} {{#kw|for}} ({{#kw|int}} i = 0; i < this.length; i++) {{#ci|?}} System.out.println(this.get(i)); {{#ci|?}} } {{#ci|?}} } +{{#x|init}}? {{#x|emit}}? ---- Get the {{#x|slides}} today! {{#c|♨}} {{http://agentzh.org/misc/slides/naming.pdf}} {{http://agentzh.org/misc/slides/naming_recap.pdf}} ---- {{#x|Contact}} me on the {{#ci|web}}! {{#c|♨}} {{agentzh@gmail.com}} ---- These slides are {{#ci|powered}} by {{#x|Sporx}} and {{img src="images/grin.png" width="41" height="41"}}{{#ci|Takahashi}}{{#x|++}} ---- {{#c|Thank you!}} ☺