分类目录归档:编码规范

6个编写优质干净代码的技巧

原文:6 Simple Tips on How to Start Writing Clean Code
作者:Alex Devero
译者:Teixeira10

【译者注】作为一名开发者,编写一手干净的代码很重要,所以在本文中作者先列举出编写干净代码的一些好处,再提出6个技巧用于编写干净代码,供开发者进行参考学习。
以下为译文:

编写干净的代码并不是一件容易的事情,这需要尝试不同的技巧和实践。问题是,在这个问题上有太多的实践和技巧,因此开发人员很难进行选择,所以要把这个问题简化一下。在本文中,将首先讨论编写干净代码的一些好处,然后将讨论6个技巧或者实践,用于编写最常用的干净代码。

以下是目录内容:

编写干净代码的好处
1. 更容易开始和继续一个项目
2.有利于团队新员工培训
3.更容易遵循编码模式

写干净代码的技巧
1.编写可读的代码
2.为变量、函数和方法使用有意义的名称
3.让每个函数或方法只执行一个任务
4.使用注释来解释代码
5.保持代码风格一致性
6.定期检查你的代码

关于编写干净代码的一些想法

写干净代码的好处

先来了解编写干净代码的一些好处。其中一个主要好处是,干净的代码可以减少花在阅读上的时间和理解代码的时间。凌乱的代码会减慢任何开发人员的速度,使开发者的工作变得更加困难。代码越混乱,开发人员就越需要花更多的时间去充分理解它,这样才能使用这些代码。而且,如果代码太乱,开发人员可能会决定停止阅读这些代码,并自己从头开始编写。

1.更容易开始和继续一个项目
先用一个简单的例子来说明这个问题。假设在很长一段时间后我们回到了之前的一个项目,也许在这段时间是一位客户联系我们去做了另一项工作。现在,想象一下,那时如果没有编写干净的代码,那么在第一眼看到代码之后,该是有多糟糕和混乱。而且,也可以知道从当初离开的地方开始编码有多困难。

因此,现在必须花更多的时间在项目上,因为我们需要理解之前编写的代码。这本来是可以避免的,如果从一开始就编写干净的代码,然而现在必须为此付出代价。而且,旧代码是如此混乱和糟糕,以至于我们可能决定从头开始。客户听到这些消息后可能不会高兴。

另一方面,干净的代码通常就没有这个问题。假设前面的例子是相反的情况,以前的代码是干净和优雅的,那么理解它需要多长时间?也许只需要读几分钟的代码就能理解所有的工作原理,而且我们可能已经开始编写一段时间了,所以在这种情况下花的精力将明显小于第一个案例,同时,客户也不会太在意。

这是编写干净代码的第一个好处,而且,这不仅适用于自己的项目,也适用于其他开发人员的工作。干净的代码可以更快地启动工作,任何人都不需要花费数小时来研究代码,相反,我们可以直接进入工作。

2.有利于团队新员工培训
编写干净代码的另一个好处与第一个好处是密切相关的,那就是可以让新员工更容易更快地使用代码。假设我们需要雇佣一个开发人员,那么她要花多长时间才能理解代码并学会使用它呢?当然这要视情况而定。如果我们的代码很乱,写得很差,她就需要花更多的时间来学习代码。另一方面,如果代码干净、易读、简单易懂,她将能够更快地开始她的工作。

有些人可能会说,这不是个问题,因为其他开发人员可以帮助她。当然这是正确的,但是帮助只应该花很短的时间,是两三次或者一两天,而并不应该是两三个星期。所以,决定雇佣另一个开发人员的目的,是来加速我们的工作,而不是减慢速度,也不是花费更多的时间来帮助她学会使用代码。

当我们努力写出干净的代码时,其他人就会向我们学习,也就更容易跟着写出干净的代码。当然,仍然需要留出一些时间来帮助每个新开发人员了解和理解代码。当然,我的意思是几天,而不是几周。此外,干净的代码将帮助团队带来更多的开发人员,并同时帮助他们理解代码。简单地说,代码越简洁就越容易解释,误解也就越少。

3.更容易遵循编码模式
有一件事需要记住,理解和学习如何使用代码是一回事。然而,这仅仅是个开始,同时还需要确保开发人员能够愿意遵循我们的编码模式。当然,使用干净的代码比混乱的代码更容易实现这个目标。这是很重要的,因为团队不仅想要编写干净的代码,而且还一直保持这种模式,这也是需要长期思考的。

另外,如果开发人员不遵循当前的编码模式该怎么办? 这个问题通常可以自行解决。假设有一群人在同一个代码基础上工作,其中一个人开始偏离标准样式。然后,团队的其他成员将推动这个开发人员遵循标准。她会接受建议,因为她不想离开这个团队。

还有一种情况,开发人员会说服团队的其他人采纳并遵循自己的编码模式。如果开发人员提出的编码模式更干净,并且能带来更好的结果,这当然是件好事。的确,编写和保持干净的代码并不意味着应该忽略任何改进它的机会,我认为应该始终对目前的做法保持可改进的态度,并努力寻找改进的机会。

因此,如果一个开发人员偏离了当前的模式,同时她的模式也更好,那么我们做出改变也许会更合适。所以在尝试其他模式之前,不应该忽视其他人的编码实践,同时我们应该继续寻找改进的余地。最后,第三种情况。开发人员决定既不采用我们的实践,也不说服我们采用她的实践。因为她将决定离开团队。

写干净代码的技巧

现在除了讨论编写干净代码的好处,也是时候学习一些技巧来帮助我们实现这个目标了。正如将在以下看到的,干净的代码包含并遵循着一些方法。这些方法使代码更干净、易读、更易于理解、更简单。当然没有必要实施所有的方法,实施并遵循一两项措施就足以带来积极的结果。

1.编写可读的代码
的确,所写的代码将会机器解释,然而这并不意味着应该忽视代码的可读性和可理解性,因为在将来总会有另一个人会使用我们写的代码。即使让别人无法访问我们的代码,但我们自己也可能在将来又重新拾起这些代码。出于这些原因,让代码便于阅读和理解是符合我们自己的利益的。那么如何实现呢?

最简单的方法是使用空格。在发布代码之前,可以缩减代码,但是没有必要让代码看起来很小型化。相反,可以使用缩进、换行和空行来使代码结构更具可读性。当决定采用这种方式时,代码的可读性和可理解性就会显著提高。然后,看着代码就可以更容易理解它了。来看两个简单的例子。
代码:

// Bad
const userData=[{userId: 1, userName: 'Anthony Johnson', memberSince: '08-01-2017', fluentIn: [ 'English', 'Greek', 'Russian']},{userId: 2, userName: 'Alice Stevens', memberSince: '02-11-2016', fluentIn: [ 'English', 'French', 'German']},{userId: 3, userName: 'Bradley Stark', memberSince: '29-08-2013', fluentIn: [ 'Czech', 'English', 'Polish']},{userId: 4, userName: 'Hirohiro Matumoto', memberSince: '08-05-2015', fluentIn: [ 'Chinese', 'English', 'German', 'Japanese']}];

// Better
const userData = [
  {
    userId: 1,
    userName: 'Anthony Johnson',
    memberSince: '08-01-2017',
    fluentIn: [
      'English',
      'Greek',
      'Russian'
    ]
  }, {
    userId: 2,
    userName: 'Alice Stevens',
    memberSince: '02-11-2016',
    fluentIn: [
      'English',
      'French',
      'German'
    ]
  }, {
    userId: 3,
    userName: 'Bradley Stark',
    memberSince: '29-08-2013',
    fluentIn: [
      'Czech',
      'English',
      'Polish'
    ]
  }, {
    userId: 4,
    userName: 'Hirohiro Matumoto',
    memberSince: '08-05-2015',
    fluentIn: [
      'Chinese',
      'English',
      'German',
      'Japanese'
    ]
  }
];

代码:

// Bad
class CarouselLeftArrow extends Component{render(){return ( <a href="#" className="carousel__arrow carousel__arrow--left" onClick={this.props.onClick}> <span className="fa fa-2x fa-angle-left"/> </a> );}};

// Better
class CarouselLeftArrow extends Component {
  render() {
    return (
      <a
        href="#"
        className="carousel__arrow carousel__arrow--left"
        onClick={this.props.onClick}
      >
        <span className="fa fa-2x fa-angle-left" />
      </a>
    );
  }
};

2.为变量、函数和方法使用有意义的名称
来看一看第二个技巧,它将帮助我们编写可理解和干净的代码。这个技巧是关于变量、函数和方法的有意义的名称。“有意义的”是什么意思?有意义的名字是描述性足够多的名字,而不仅仅是编写者自己才能够理解的变量、函数或方法。换句话说,名称本身应该根据变量、函数或方法的内容和使用方式来定义。
代码:

// Bad
const fnm = ‘Tom’;
const lnm = ‘Hanks’
const x = 31;
const l = lstnm.length;
const boo = false;
const curr = true;
const sfn = ‘Remember the name’;
const dbl = [‘1984’, ‘1987’, ‘1989’, ‘1991’].map((i) => {
  return i * 2;
});

// Better
const firstName = ‘Tom’;
const lastName = ‘Hanks’
const age = 31;
const lastNameLength = lastName.length;
const isComplete = false;
const isCurrentlyActive = true;
const songFileName = ‘Remember the name’;
const yearsDoubled = [‘1984’, ‘1987’, ‘1989’, ‘1991’].map((year) => {
  return year * 2;
});

然而需要注意的是,使用描述性名称并不意味着可以随意使用任意多个字符。一个好的经验则是将名字限制在3或4个单词。如果需要使用超过4个单词,说明这个函数或方法需要同时执行很多的任务,所以应该简化代码,只使用必要的字符。

3.让一个函数或方法只执行一个任务
当开始编写代码时,使用的函数和方法看起来就像一把瑞士军刀,几乎可以处理任何事情,但是很难找到一个好的命名。另外,除了编写者,几乎没有人知道函数是用来做什么的以及该如何使用它。有时我就会遇到这些问题,我在这方面做的很不好。

然后,有人提出了一个很好的建议:让每个函数或方法只执行一个任务。这个简单的建议改变了一切,帮助我写出了干净的代码,至少比以前更干净了。从那以后,其他人终于能够理解我的代码了,或者说,他们不需要像以前一样花很多时间去读懂代码了,功能和方法也变得更好理解。在相同的输入下,总是能产生相同的输出,而且,命名也变得容易得多。

如果你很难找到函数和方法的描述性名称,或者需要编写冗长的指令以便其他人可以使用,那请考虑这个建议,让每个函数或方法只执行一个任务。如果你的功能和方法看起来像瑞士军刀一样无所不能,那请你执行这个方法,相信我,这种多才多艺不是一种优势。这是一个相当不利的情况,可能会产生事与愿违的结果。

附注:这种让每一个函数或方法只执行一项任务的做法被称为保持纯函数。这种编码实践来自于函数式编程的概念。如果你想了解更多,我推荐阅读《So You Want to be a Functional Programmer series[4]》。
代码:

// Examples of pure functions
function subtract(x, y) {
    return x - y;
}

function multiply(x, y) {
    return x * y;
}

// Double numbers in an array
function doubleArray(array) {
  return array.map(number => number * 2)
}

4.更容易遵循编码模式
不管多么努力地为变量、函数和方法想出有意义的名字,代码仍然不可能完全清晰易懂,还有一些思路需要进行解释。问题可能不是代码很难理解或使用,相反,其他人可能不理解为什么要实现这个函数或方法,或者为什么要以特定的方式创建它。意思是,创建函数或方法的意图还不清楚。

有时可能不得不采用非传统的方法来解决问题,因为没有足够的时间来想出更好的解决方案,这也很难用代码来解释。所以,通过代码注释可以帮助解决这个问题,也可以帮助我们向其他人解释为什么写了这个方法,为什么要用这种特定的方式来写,那么其他人就不必猜测这些方法或函数的用途了。

更重要的是,当我们使用注来解释代码后,其他人可能会找到一个更好的方法来解决这个问题并改进代码。这是有可能的,因为他们知道问题是什么,以及期望的结果是什么。如果不知道这些信息,其他人就很难创建更好的解决方案,或者他们可能不会去尝试,因为他们认为没有必要去修改创建者自己的想法。

因此,每当自己决定使用一些快速修复或非传统的方法时,要用注释来解释为什么这么做。最好是用一两行注释来解释,而不用别人来猜测。

也就是说,我们应该只在必要的时候使用注释,而不是解释糟糕的代码。编写无穷无尽的注释将无助于将糟糕的代码转换成干净的代码。如果代码不好,应该通过改进代码来解决这个问题,而不是添加一些如何使用它的说明。编写干净的代码更重要。

5.保持代码风格一致性
当我们有自己喜欢的特定编码方式或风格时,就会在任何地方一直使用它。但在不同的项目中使用不同的编码风格不是一个好主意,而且也不可能很自然地回到以前的代码,所以仍然需要一些时间来理解在项目中使用的编码风格。

最好的方法是选择一套编码方式,然后在所有的项目中坚持使用。这样的话,回到之前的旧代码会变得更容易。当然,尝试新的编码方式是一件好事,它可以帮助我们找到更好的方法来开展工作。但是最好是在不同的实验项目或练习上尝试不同的编码风格,而不是在主要项目上进行。

另外,当我们决定做一些试验的时候,就应该尝试多次练习,应该花时间彻底地做好。只有真正确信喜欢这种做法,并且对它感到满意时,才应该去实施它。而且决定这样做的时候,最好应用在所有的项目中。是的,这需要时间,这也会促使我们正确地思考。

6.检查你的代码

这是最后一个技巧。不仅仅是编写干净的代码,还要完成最后的工作,那就是需要维护干净代码。我们应该定期检查代码,并试着改进它。否则,如果不审查和更新我们的旧代码,它很快就会过时,就像我们的设备一样。如果想让代码保持最佳状态,就需要定期更新它们。

对于每天使用的代码,情况也是如此。代码会变得更加复杂和混乱,所有应该避免这种情况发生,并保持代码干净。实现这一点的唯一方法是定期检查我们的代码。换句话说,我们需要保持它。对于那些未来不再关心的项目来说,这可能是不必要的,但对其他的来说,维护代码是工作的一部分。

关于编写干净代码的一些想法

今天讨论的这六种做法,可能不是影响最大的,也可能不是最重要的,但这些是经验丰富的开发人员最常提到的,这也就是我选择它们的原因。我希望这些实践或技巧能够帮助你开始编写干净的代码。现在,就像所有的事情一样,最重要的是开始。所以,至少选一个技巧,然后试一试。

优秀程序员眼中的整洁代码

有多少程序员,就有多少定义。所以我只询问了一些非常知名且经验丰富的程序员。
Bjarne Stroustrup,C++语言发明者,C++ Programming Language(中译版《C++程序设计语言》)一书作者。

我喜欢优雅和高效的代码。代码逻辑应当直截了当,叫缺陷难以隐藏;尽量减少依赖关系,使之便于维护;依据某种分层战略完善错误处理代码;性能调至最优,省得引诱别人做没规矩的优化,搞出一堆混乱来。整洁的代码只做好一件事。

Bjarne 用了“优雅”一词。说得好!我 MacBook 上的词典提供了如下定义:外表或举止上令人愉悦的优美和雅观;令人愉悦的精致和简单。注意对“愉悦”一词的强调。Bjarne 显然认为整洁的代码读起来令人愉悦。读这种代码,就像见到手工精美的音乐盒或者设计精良的汽车一般,让你会心一笑。

Bjarne 也提到效率——而且两次提及。这话出自 C++ 发明者之口,或许并不出奇;不过我认为并非是在单纯追求速度。被浪费掉的运算周期并不雅观,并不令人愉悦。留意 Bjarne 怎么描述那种不雅观的结果。他用了“引诱”这个词。诚哉斯言。糟糕的代码引发混乱!别人修改糟糕的代码时,往往会越改越烂。

务实的 Dave Thomas 和 Andy Hunt 从另一角度阐述了这种情况。他们提到破窗理论4。窗户破损了的建筑让人觉得似乎无人照管。于是别人也再不关心。他们放任窗户继续破损。最终自己也参加破坏活动,在外墙上涂鸦,任垃圾堆积。一扇破损的窗户开辟了大厦走向倾颓的道路。

Bjarne 也提到完善错误处理代码。往深处说就是在细节上花心思。敷衍了事的错误处理代码只是程序员忽视细节的一种表现。此外还有内存泄漏,还有竞态条件代码。还有前后不一致的命名方式。结果就是凸现出整洁代码对细节的重视。

Bjarne 以“整洁的代码只做好一件事”结束论断。毋庸置疑,软件设计的许多原则最终都会归结为这句警语。有那么多人发表过类似的言论。糟糕的代码想做太多事,它意图混乱、目的含混。整洁的代码力求集中。每个函数、每个类和每个模块都全神贯注于一事,完全不受四周细节的干扰和污染。

Grady Booch,Object Oriented Analysis and Design with Applications(中译版《面向对象分析与设计》)一书作者。

整洁的代码简单直接。整洁的代码如同优美的散文。整洁的代码从不隐藏设计者的意图,充满了干净利落的抽象和直截了当的控制语句。

Grady 的观点与 Bjarne 的观点有类似之处,但他从可读性的角度来定义。我特别喜欢“整洁的代码如同优美的散文”这种看法。想想你读过的某本好书。回忆一下,那些文字是如何在脑中形成影像!就像是看了场电影,对吧?还不止!你还看到那些人物,听到那些声音,体验到那些喜怒哀乐。

阅读整洁的代码和阅读 Lord of the Rings(中译版《指环王》)自然不同。不过,仍有可类比之处。如同一本好的小说般,整洁的代码应当明确地展现出要解决问题的张力。它应当将这种张力推至高潮,以某种显而易见的方案解决问题和张力,使读者发出“啊哈!本当如此!”的感叹。

窃以为 Grady 所谓“干净利落的抽象”(crisp abstraction),乃是绝妙的矛盾修辞法。毕竟 crisp 几乎就是“具体”(concrete)的同义词。我 MacBook 上的词典这样定义 crisp 一词:果断决绝,就事论事,没有犹豫或不必要的细节。尽管有两种不同的定义,该词还是承载了有力的信息。代码应当讲述事实,不引人猜测。它只该包含必需之物。读者应当感受到我们的果断决绝。

“老大”Dave Thomas,OTI 公司创始人,Eclipse 战略教父。

整洁的代码应可由作者之外的开发者阅读和增补。它应当有单元测试和验收测试。它使用有意义的命名。它只提供一种而非多种做一件事的途径。它只有尽量少的依赖关系,而且要明确地定义和提供清晰、尽量少的 API。代码应通过其字面表达含义,因为不同的语言导致并非所有必需信息均可通过代码自身清晰表达。

Dave 老大在可读性上和 Grady 持相同观点,但有一个重要的不同之处。Dave 断言,整洁的代码便于其他人加以增补。这看似显而易见,但亦不可过分强调。毕竟易读的代码和易修改的代码之间还是有区别的。

Dave 将整洁系于测试之上!要在十年之前,这会让人大跌眼镜。但测试驱动开发(Test Driven Development)已在行业中造成了深远影响,成为基础规程之一。Dave 说得对。没有测试的代码不干净。不管它有多优雅,不管有多可读、多易理解,微乎测试,其不洁亦可知也。

Dave 两次提及“尽量少”。显然,他推崇小块的代码。实际上,从有软件起人们就在反复强调这一点。越小越好。

Dave 也提到,代码应在字面上表达其含义。这一观点源自 Knuth 的“字面编程”(literate programming)5。结论就是应当用人类可读的方式来写代码。

Michael Feathers,Working Effectively with Legacy Code(中译版《修改代码的艺术》)一书作者。

我可以列出我留意到的整洁代码的所有特点,但其中有一条是根本性的。整洁的代码总是看起来像是某位特别在意它的人写的。几乎没有改进的余地。代码作者什么都想到了,如果你企图改进它,总会回到原点,赞叹某人留给你的代码——全心投入的某人留下的代码。

一言以蔽之:在意。这就是本书的题旨所在。或许该加个副标题,如何在意代码

Michael 一针见血。整洁代码就是作者着力照料的代码。有人曾花时间让它保持简单有序。他们适当地关注到了细节。他们在意过。

Ron Jeffries,Extreme Programming Installed(中译版《极限编程实施》)以及 Extreme Programming Adventures in C#(中译版《C#极限编程探险》)作者。

Ron 初入行就在战略空军司令部(Strategic Air Command)编写 Fortran 程序,此后几乎在每种机器上编写过每种语言的代码。他的言论值得咀嚼。

近年来,我开始研究贝克的简单代码规则,差不多也都琢磨透了。简单代码,依其重要顺序:

能通过所有测试;

没有重复代码;

体现系统中的全部设计理念;

包括尽量少的实体,比如类、方法、函数等。

在以上诸项中,我最在意代码重复。如果同一段代码反复出现,就表示某种想法未在代码中得到良好的体现。我尽力去找出到底那是什么,然后再尽力更清晰地表达出来。

在我看来,有意义的命名是体现表达力的一种方式,我往往会修改好几次才会定下名字来。借助 Eclipse 这样的现代编码工具,重命名代价极低,所以我无所顾忌。然而,表达力还不只体现在命名上。我也会检查对象或方法是否想做的事太多。如果对象功能太多,最好是切分为两个或多个对象。如果方法功能太多,我总是使用抽取手段(Extract Method)重构之,从而得到一个能较为清晰地说明自身功能的方法,以及另外数个说明如何实现这些功能的方法。

消除重复和提高表达力让我在整洁代码方面获益良多,只要铭记这两点,改进脏代码时就会大有不同。不过,我时常关注的另一规则就不太好解释了。

这么多年下来,我发现所有程序都由极为相似的元素构成。例如“在集合中查找某物”。不管是雇员记录数据库还是名-值对哈希表,或者某类条目的数组,我们都会发现自己想要从集合中找到某一特定条目。一旦出现这种情况,我通常会把实现手段封装到更抽象的方法或类中。这样做好处多多。

可以先用某种简单的手段,比如哈希表来实现这一功能,由于对搜索功能的引用指向了我那个小小的抽象,就能随需应变,修改实现手段。这样就既能快速前进,又能为未来的修改预留余地。

另外,该集合抽象常常提醒我留意“真正”在发生的事,避免随意实现集合行为,因为我真正需要的不过是某种简单的查找手段。

减少重复代码,提高表达力,提早构建简单抽象。这就是我写整洁代码的方法。

Ron 以寥寥数段文字概括了本书的全部内容。不要重复代码,只做一件事,表达力,小规模抽象。该有的都有了。

Ward Cunningham,Wiki 发明者,eXtreme Programming(极限编程)的创始人之一,Smalltalk 语言和面向对象的思想领袖。所有在意代码者的教父。

如果每个例程都让你感到深合己意,那就是整洁代码。如果代码让编程语言看起来像是专为解决那个问题而存在,就可以称之为漂亮的代码。

这种说法很 Ward。它教你听了之后就点头,然后继续听下去。如此在理,如此浅显,绝不故作高深。你大概以为此言深合己意吧。再走近点看看。

“……深合己意”。你最近一次看到深合己意的模块是什么时候?模块多半都繁复难解吧?难道没有触犯规则吗?你不是也曾挣扎着想抓住些从整个系统中散落而出的线索,编织进你在读的那个模块吗?你最近一次读到某段代码、并且如同对 Ward 的说法点头一般对这段代码点头,是什么时候的事了?

Ward 期望你不会为整洁代码所震惊。你无需花太多力气。那代码就是深合你意。它明确、简单、有力。每个模块都为下一个模块做好准备。每个模块都告诉你下一个模块会是怎样的。整洁的程序好到你根本不会注意到它。设计者把它做得像一切其他设计般简单。

那 Ward 有关“美”的说法又如何呢?我们都曾面临语言不是为要解决的问题所设计的困境。但 Ward 的说法又把球踢回我们这边。他说,漂亮的代码让编程语言像是专为解决那个问题而存在!所以,让语言变得简单的责任就在我们身上了!当心,语言是冥顽不化的!是程序员让语言显得简单。

 

摘自:http://begeek.cn/post/7210.html?_biz=MjM5OTA1MDUyMA==&mid=407358558&idx=2&sn=b21877f23bf4063fa311185009c1f0b7&scene=0#wechat_redirect1468885896550

10个精妙的Java编码最佳实践

本文由 ImportNew – liken 翻译自 jooq。欢迎加入Java小组。转载请参见文章末尾的要求。

这是一个比Josh Bloch的Effective Java规则更精妙的10条Java编码实践的列表。和Josh Bloch的列表容易学习并且关注日常情况相比,这个列表将包含涉及API/SPI设计中不常见的情况,可能有很大影响。

我在编写和维护jOOQ(Java中内部DSL建模的SQL)时遇到过这些。作为一个内部DSL,jOOQ最大限度的挑战了Java的编译器和泛型,把泛型,可变参数和重载结合在一起,Josh Bloch可能不会推荐的这种太宽泛的API。

让我与你分享10个微妙的Java编码最佳实践:

1. 牢记C++的析构函数

记得C++的析构函数?不记得了?那么你真的很幸运,因为你不必去调试那些由于对象删除后分配的内存没有被释放而导致内存泄露的代码。感谢Sun/Oracle实现的垃圾回收机制吧!

尽管如此,析构函数仍提供了一个有趣的特征。它理解逆分配顺序释放内存。记住在Java中也是这样的,当你操作类析构函数语法:

  • 使用JUnit的@Before和@After注释
  • 分配,释放JDBC资源
  • 调用super方法

还有其他各种用例。这里有一个具体的例子,说明如何实现一些事件侦听器的SPI:

1
2
3
4
5
6
7
8
9
10
11
@Override
public void beforeEvent(EventContext e) {
    super.beforeEvent(e);
    // Super code before my code
}
@Override
public void afterEvent(EventContext e) {
    // Super code after my code
    super.afterEvent(e);
}

臭名昭著的哲学家就餐问题是另一个说明它为什么重要的好例子。 关于哲学家用餐的问题,请查看链接:
http://adit.io/posts/2013-05-11-The-Dining-Philosophers-Problem-With-Ron-Swanson.html

规则:无论何时使用before/after, allocate/free, take/return语义实现逻辑时,考虑是否逆序执行after/free/return操作。

2. 不要相信你早期的SPI演进判断

向客户提供SPI可以使他们轻松的向你的库/代码中注入自定义行为的方法。当心你的SPI演进判断可能会迷惑你,使你认为你 (不)打算需要附加参数 当然,不应当过早增加功能。但一旦你发布了你的SPI,一旦你决定遵循语义版本控制,当你意识到在某种情况下你可能需要另外一个参数时,你会真的后悔在SPI中增加一个愚蠢的单参数的方法:

1
2
3
4
interface EventListener {
    // Bad
    void message(String message);
}

如果你也需要消息ID和消息源,怎么办?API演进将会阻止你向上面的类型添加参数。当然,有了Java8,你可以添加一个defender方法,“防御”你早期糟糕的设计决策:

1
2
3
4
5
6
7
8
9
10
11
12
interface EventListener {
    // Bad
    default void message(String message) {
        message(message, null, null);
    }
    // Better?
    void message(
        String message,
        Integer id,
        MessageSource source
    );
}

注意,不幸的是,defender方法不能使用final修饰符
但是比起使用许多方法污染你的SPI,使用上下文对象(或者参数对象)会好很多。

1
2
3
4
5
6
7
8
9
10
interface MessageContext {
    String message();
    Integer id();
    MessageSource source();
}
interface EventListener {
    // Awesome!
    void message(MessageContext context);
}

比起EventListner SPI你可以更容易演进MessageContext API,因为很少用户会实现它。
规则: 无论何时指定SPI时,考虑使用上下文/参数对象,而不是写带有固定参数的方法。
备注: 通过专用的MessageResult类型交换结果也是一个好主意,该类型可以使用建设者API构造它。这样将大大增加SPI进化的灵活性。

3. 避免返回匿名,本地或者内部类

Swing程序员通常只要按几下快捷键即可生成成百上千的匿名类。在多数情况下,只要遵循接口、不违反SPI子类型的生命周期(SPI subtype lifecycle),这样做也无妨。 但是不要因为一个简单的原因——它们会保存对外部类的引用,就频繁的使用匿名、局部或者内部类。因为无论它们走到哪,外部类就得跟到哪。例如,在局部类的域外操作不当的话,那么整个对象图就会发生微妙的变化从而可能引起内存泄露。

规则:在编写匿名、局部或内部类前请三思能否将它转化为静态的或普通的顶级类,从而避免方法将它们的对象返回到更外层的域中。

注意:使用双层花括号来初始化简单对象:

1
2
3
4
new HashMap<String, String>() {{
  put("1", "a");
  put("2", "b");
}}

这个方法利用了 JLS §8.6规范里描述的实例初始化方法(initializer)。表面上看起来不错,但实际上不提倡这种做法。因为要是使用完全独立的HashMap对象,那么实例就不会一直保存着外部对象的引用。此外,这也会让类加载器管理更多的类。

4. 现在就开始编写SAM!

Java8的脚步近了。伴随着Java8带来了lambda表达式,无论你是否喜欢。尽管你的API用户可能会喜欢,但是你最好确保他们可以尽可能经常的使用。因此除非你的API接收简单的“标量”类型,比如int、long、String 、Date,否则让你的API尽可能经常的接收SAM。

什么是SAM?SAM是单一抽象方法[类型]。也称为函数接口,不久会被注释为@FunctionalInterface。这与规则2很配,EventListener实际上就是一个SAM。最好的SAM只有一个参数,因为这将会进一步简化lambda表达式的编写。设想编写

1
listeners.add(c -> System.out.println(c.message()));

来替代

1
2
3
4
5
6
listeners.add(new EventListener() {
  @Override
  public void message(MessageContext c) {
    System.out.println(c.message()));
  }
});

设想以JOOX的方式来处理XML。JOOX就包含很多的SAM:

1
2
3
4
5
6
7
$(document)
  // Find elements with an ID
  .find(c -> $(c).id() != null)
  // Find their child elements
  .children(c -> $(c).tag().equals("order"))
  // Print all matches
  .each(c -> System.out.println($(c)))

规则:对你的API用户好一点儿,从现在开始编写SAM/函数接口。

备注:有许多关于Java8 lambda表达式和改善的Collections API的有趣的博客:

5.避免让方法返回null

我曾写过1、2篇关于java NULLs的文章,也讲解过Java8中引入新的Optional类。从学术或实用的角度来看,这些话题还是比较有趣的。

尽管现阶段Null和NullPointerException依然是Java的硬伤,但是你仍可以设计出不会出现任何问题的API。在设计API时,应当尽可能的避免让方法返回null,因为你的用户可能会链式调用方法:

1
initialise(someArgument).calculate(data).dispatch();

从上面代码中可看出,任何一个方法都不应返回null。实际上,在通常情况下使用null会被认为相当的异类。像  jQuery或 jOOX这样的库在可迭代的对象上已完全的摒弃了null。

Null通常用在延迟初始化中。在许多情况下,在不严重影响性能的条件下,延迟初始化也应该被避免。实际上,如果涉及的数据结构过于庞大,那么就要慎用延迟初始化。

规则:无论何时方法都应避免返回null。null仅用来表示“未初始化”或“不存在”的语义。

6.设计API时永远不要返回空(null)数组或List

尽管在一些情况下方法返回值为null是可以的,但是绝不要返回空数组或空集合!请看 java.io.File.list()方法,它是这样设计的:

此方法会返回一个指定目录下所有文件或目录的字符串数组。如果目录为空(empty)那么返回的数组也为空(empty)。如果指定的路径不存在或发生I/O错误,则返回null。

因此,这个方法通常要这样使用:

1
2
3
4
5
6
7
8
9
10
11
File directory = // ...
if (directory.isDirectory()) {
  String[] list = directory.list();
  if (list != null) {
    for (String file : list) {
      // ...
    }
  }
}
1
大家觉得null检查有必要吗?大多数I/O操作会产生IOExceptions,但这个方法却只返回了null。Null是无法存放I/O错误信息的。因此这样的设计,有以下3方面的不足:
  • Null无助于发现错误
  • Null无法表明I/O错误是由File实例所对应的路径不正确引起的
  • 每个人都可能会忘记判断null情况

以集合的思维来看待问题的话,那么空的(empty)的数组或集合就是对“不存在”的最佳实现。返回空(null)数组或集合几乎是无任何实际意义的,除非用于延迟初始化。

规则:返回的数组或集合不应为null。

7. 避免状态,使用函数

HTTP的好处是无状态。所有相关的状态在每次请求和响应中转移。这是REST命名的本质:含状态传输(Representational state transfer)。在Java中这样做也很赞。当方法接收状态参数对象的时候从规则2的角度想想这件事。如果状态通过这种对象传输,而不是从外边操作状态,那么事情将会更简单。以JDBC为例。下述例子从一个存储的程序中读取一个光标。

1
2
3
4
5
6
7
8
9
10
11
12
CallableStatement s =
  connection.prepareCall("{ ? = ... }");
// Verbose manipulation of statement state:
s.registerOutParameter(1, cursor);
s.setString(2, "abc");
s.execute();
ResultSet rs = s.getObject(1);
// Verbose manipulation of result set state:
rs.next();
rs.next();

这使得JDBC API如此的古怪。每个对象都是有状态的,难以操作。具体的说,有两个主要的问题:

  • 在多线程环境很难正确的处理有状态的API
  • 很难让有状态的资源全局可用,因为状态没有被描述

规则:更多的以函数风格实现。通过方法参数转移状态。极少操作对象状态。

8. 短路式 equals()

这是一个比较容易操作的方法。在比较复杂的对象系统中,你可以获得显著的性能提升,只要你在所有对象的equals()方法中首先进行相等判断:

1
2
3
4
5
@Override
public boolean equals(Object other) {
  if (this == other) return true;
  // 其它相等判断逻辑...
}

注意,其它短路式检查可能涉及到null值检查,所以也应当加进去:

1
2
3
4
5
6
@Override
public boolean equals(Object other) {
  if (this == other) return true;
  if (other == null) return false;
  // Rest of equality logic...
}

规则: 在你所有的equals()方法中使用短路来提升性能。

9. 尽量使方法默认为final

有些人可能不同意这一条,因为使方法默认为final与Java开发者的习惯相违背。但是如果你对代码有完全的掌控,那么使方法默认为final是肯定没错的:

  • 如果你确实需要覆盖(override)一个方法(你真的需要?),你仍然可以移除final关键字
  • 你将永远不会意外地覆盖(override)任何方法

这特别适用于静态方法,在这种情况下“覆盖”(实际上是遮蔽)几乎不起作用。我最近在Apache Tika中遇到了一个很糟糕的遮蔽静态方法的例子。看一下:

TikaInputStream扩展了TaggedInputStream,以一种相对不同的实现遮蔽了它的静态get()方法。

与常规方法不同,静态方法不能互相覆盖,因为调用的地方在编译时就绑定了静态方法调用。如果你不走运,你可能会意外获得错误的方法。

规则:如果你完全掌控你的API,那么使尽可能多的方法默认为final。

10. 避免方法(T…)签名

在特殊场合下使用“accept-all”变量参数方法接收一个Object…参数就没有错的:

1
void acceptAll(Object... all);

编写这样的方法为Java生态系统带来一点儿JavaScript的感觉。当然你可能想要根据真实的情形限制实际的类型,比如String…。因为你不想要限制太多,你可能会认为用泛型T取代Object是一个好想法:

1
void acceptAll(T... all);

但是不是。T总是会被推断为Object。实际上你可能仅仅认为上述方法中不能使用泛型。更重要的是你可能认为你可以重载上述方法,但是你不能:

1
2
void acceptAll(T... all);
void acceptAll(String message, T... all);

这看起来好像你可以可选地传递一个String消息到方法。但是这个调用会发生什么呢?

1
acceptAll("Message", 123, "abc");

编译器将T推断为<? extends Serializable & Comparable<?>>,这将会使调用不明确!

所以无论何时你有一个“accept-all”签名(即使是泛型),你将永远不能类型安全地重载它。API使用者可能仅仅在走运的时候才会让编译器“偶然地”选择“正确的”方法。但是也可能使用accept-all方法或者无法调用任何方法。

规则: 如果可能,避免“accept-all”签名。如果不能,不要重载这样的方法。

结论

Java是一个野兽。不像其它更理想主义的语言,它慢慢地演进为今天的样子。这可能是一件好事,因为以Java的开发速度就已经有成百上千个警告,而且这些警告只能通过多年的经验去把握。

Google Java编程风格指南

http://hawstein.com/posts/google-java-style.html

Google Java编程风格指南

January 20, 2014
作者:Hawstein
出处:http://hawstein.com/posts/google-java-style.html
声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|Creative Commons BY-NC-ND 3.0 ,转载请注明作者及出处。

目录

  1. 前言
  2. 源文件基础
  3. 源文件结构
  4. 格式
  5. 命名约定
  6. 编程实践
  7. Javadoc
  8. 后记

前言

这份文档是Google Java编程风格规范的完整定义。当且仅当一个Java源文件符合此文档中的规则, 我们才认为它符合Google的Java编程风格。

与其它的编程风格指南一样,这里所讨论的不仅仅是编码格式美不美观的问题, 同时也讨论一些约定及编码标准。然而,这份文档主要侧重于我们所普遍遵循的规则, 对于那些不是明确强制要求的,我们尽量避免提供意见。

1.1 术语说明

在本文档中,除非另有说明:

  1. 术语class可表示一个普通类,枚举类,接口或是annotation类型(@interface)
  2. 术语comment只用来指代实现的注释(implementation comments),我们不使用“documentation comments”一词,而是用Javadoc。

其他的术语说明会偶尔在后面的文档出现。

1.2 指南说明

本文档中的示例代码并不作为规范。也就是说,虽然示例代码是遵循Google编程风格,但并不意味着这是展现这些代码的唯一方式。 示例中的格式选择不应该被强制定为规则。

源文件基础

2.1 文件名

源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为.java

2.2 文件编码:UTF-8

源文件编码格式为UTF-8。

2.3 特殊字符

2.3.1 空白字符

除了行结束符序列,ASCII水平空格字符(0x20,即空格)是源文件中唯一允许出现的空白字符,这意味着:

  1. 所有其它字符串中的空白字符都要进行转义。
  2. 制表符不用于缩进。

2.3.2 特殊转义序列

对于具有特殊转义序列的任何字符(\b, \t, \n, \f, \r, \“, \‘及\),我们使用它的转义序列,而不是相应的八进制(比如\012)或Unicode(比如\u000a)转义。

2.3.3 非ASCII字符

对于剩余的非ASCII字符,是使用实际的Unicode字符(比如∞),还是使用等价的Unicode转义符(比如\u221e),取决于哪个能让代码更易于阅读和理解。

Tip: 在使用Unicode转义符或是一些实际的Unicode字符时,建议做些注释给出解释,这有助于别人阅读和理解。

例如:

String unitAbbrev = "μs";                                 | 赞,即使没有注释也非常清晰
String unitAbbrev = "\u03bcs"; // "μs"                    | 允许,但没有理由要这样做
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"    | 允许,但这样做显得笨拙还容易出错
String unitAbbrev = "\u03bcs";                            | 很糟,读者根本看不出这是什么
return '\ufeff' + content; // byte order mark             | Good,对于非打印字符,使用转义,并在必要时写上注释

Tip: 永远不要由于害怕某些程序可能无法正确处理非ASCII字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时,它自然无法正确运行, 你就会去fix这些问题的了。(言下之意就是大胆去用非ASCII字符,如果真的有需要的话)

源文件结构

一个源文件包含(按顺序地):

  1. 许可证或版权信息(如有需要)
  2. package语句
  3. import语句
  4. 一个顶级类(只有一个)

以上每个部分之间用一个空行隔开。

3.1 许可证或版权信息

如果一个文件包含许可证或版权信息,那么它应当被放在文件最前面。

3.2 package语句

package语句不换行,列限制(4.4节)并不适用于package语句。(即package语句写在一行里)

3.3 import语句

3.3.1 import不要使用通配符

即,不要出现类似这样的import语句:import java.util.*;

3.3.2 不要换行

import语句不换行,列限制(4.4节)并不适用于import语句。(每个import语句独立成行)

3.3.3 顺序和间距

import语句可分为以下几组,按照这个顺序,每组由一个空行分隔:

  1. 所有的静态导入独立成组
  2. com.google imports(仅当这个源文件是在com.google包下)
  3. 第三方的包。每个顶级包为一组,字典序。例如:android, com, junit, org, sun
  4. java imports
  5. javax imports

组内不空行,按字典序排列。

3.4 类声明

3.4.1 只有一个顶级类声明

每个顶级类都在一个与它同名的源文件中(当然,还包含.java后缀)。

例外:package-info.java,该文件中可没有package-info类。

3.4.2 类成员顺序

类的成员顺序对易学性有很大的影响,但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。 最重要的一点,每个类应该以某种逻辑去排序它的成员,维护者应该要能解释这种排序逻辑。比如, 新的方法不能总是习惯性地添加到类的结尾,因为这样就是按时间顺序而非某种逻辑来排序的。

3.4.2.1 重载:永不分离

当一个类有多个构造函数,或是多个同名方法,这些函数/方法应该按顺序出现在一起,中间不要放进其它函数/方法。

格式

术语说明:块状结构(block-like construct)指的是一个类,方法或构造函数的主体。需要注意的是,数组初始化中的初始值可被选择性地视为块状结构(4.8.3.1节)。

4.1 大括号

4.1.1 使用大括号(即使是可选的)

大括号与if, else, for, do, while语句一起使用,即使只有一条语句(或是空),也应该把大括号写上。

4.1.2 非空块:K & R 风格

对于非空块和块状结构,大括号遵循Kernighan和Ritchie风格 (Egyptian brackets):

  • 左大括号前不换行
  • 左大括号后换行
  • 右大括号前换行
  • 如果右大括号是一个语句、函数体或类的终止,则右大括号后换行; 否则不换行。例如,如果右大括号后面是else或逗号,则不换行。

示例:

return new MyClass() {
  @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    }
  }
};

4.8.1节给出了enum类的一些例外。

4.1.3 空块:可以用简洁版本

一个空的块状结构里什么也不包含,大括号可以简洁地写成{},不需要换行。例外:如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ,即使大括号内没内容,右大括号也要换行。

示例:

void doNothing() {}

4.2 块缩进:2个空格

每当开始一个新的块,缩进增加2个空格,当块结束时,缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见4.1.2节中的代码示例)

4.3 一行一个语句

每个语句后要换行。

4.4 列限制:80或100

一个项目可以选择一行80个字符或100个字符的列限制,除了下述例外,任何一行如果超过这个字符数限制,必须自动换行。

例外:

  1. 不可能满足列限制的行(例如,Javadoc中的一个长URL,或是一个长的JSNI方法参考)。
  2. packageimport语句(见3.2节和3.3节)。
  3. 注释中那些可能被剪切并粘贴到shell中的命令行。

4.5 自动换行

术语说明:一般情况下,一行长代码为了避免超出列限制(80或100个字符)而被分为多行,我们称之为自动换行(line-wrapping)。

我们并没有全面,确定性的准则来决定在每一种情况下如何自动换行。很多时候,对于同一段代码会有好几种有效的自动换行方式。

Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题(是合理缩短命名长度吧)

4.5.1 从哪里断开

自动换行的基本准则是:更倾向于在更高的语法级别处断开。

  1. 如果在非赋值运算符处断开,那么在该符号前断开(比如+,它将位于下一行)。注意:这一点与Google其它语言的编程风格不同(如C++和JavaScript)。 这条规则也适用于以下“类运算符”符号:点分隔符(.),类型界限中的&(<T extends Foo & Bar>),catch块中的管道符号(catch (FooException | BarException e)
  2. 如果在赋值运算符处断开,通常的做法是在该符号后断开(比如=,它与前面的内容留在同一行)。这条规则也适用于foreach语句中的分号。
  3. 方法名或构造函数名与左括号留在同一行。
  4. 逗号(,)与其前面的内容留在同一行。

4.5.2 自动换行时缩进至少+4个空格

自动换行时,第一行后的每一行至少比第一行多缩进4个空格(注意:制表符不用于缩进。见2.3.1节)。

当存在连续自动换行时,缩进可能会多缩进不只4个空格(语法元素存在多级时)。一般而言,两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。

第4.6.3水平对齐一节中指出,不鼓励使用可变数目的空格来对齐前面行的符号。

4.6 空白

4.6.1 垂直空白

以下情况需要使用一个空行:

  1. 类内连续的成员之间:字段,构造函数,方法,嵌套类,静态初始化块,实例初始化块。
    • 例外:两个连续字段之间的空行是可选的,用于字段的空行主要用来对字段进行逻辑分组。
  2. 在函数体内,语句的逻辑分组间使用空行。
  3. 类内的第一个成员前或最后一个成员后的空行是可选的(既不鼓励也不反对这样做,视个人喜好而定)。
  4. 要满足本文档中其他节的空行要求(比如3.3节:import语句)

多个连续的空行是允许的,但没有必要这样做(我们也不鼓励这样做)。

4.6.2 水平空白

除了语言需求和其它规则,并且除了文字,注释和Javadoc用到单个空格,单个ASCII空格也出现在以下几个地方:

  1. 分隔任何保留字与紧随其后的左括号(()(如if, for catch等)。
  2. 分隔任何保留字与其前面的右大括号(})(如else, catch)。
  3. 在任何左大括号前({),两个例外:
    • @SomeAnnotation({a, b})(不使用空格)。
    • String[][] x = foo;(大括号间没有空格,见下面的Note)。
  4. 在任何二元或三元运算符的两侧。这也适用于以下“类运算符”符号:
    • 类型界限中的&(<T extends Foo & Bar>)。
    • catch块中的管道符号(catch (FooException | BarException e)。
    • foreach语句中的分号。
  5. , : ;及右括号())后
  6. 如果在一条语句后做注释,则双斜杠(//)两边都要空格。这里可以允许多个空格,但没有必要。
  7. 类型和变量之间:List list。
  8. 数组初始化中,大括号内的空格是可选的,即new int[] {5, 6}new int[] { 5, 6 }都是可以的。

Note:这个规则并不要求或禁止一行的开关或结尾需要额外的空格,只对内部空格做要求。

4.6.3 水平对齐:不做要求

术语说明:水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。

这是允许的(而且在不少地方可以看到这样的代码),但Google编程风格对此不做要求。即使对于已经使用水平对齐的代码,我们也不需要去保持这种风格。

以下示例先展示未对齐的代码,然后是对齐的代码:

private int x; // this is fine
private Color color; // this too

private int   x;      // permitted, but future edits
private Color color;  // may leave it unaligned

Tip:对齐可增加代码可读性,但它为日后的维护带来问题。考虑未来某个时候,我们需要修改一堆对齐的代码中的一行。 这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格), 这就会让你做许多的无用功,增加了reviewer的工作并且可能导致更多的合并冲突。

4.7 用小括号来限定组:推荐

除非作者和reviewer都认为去掉小括号也不会使代码被误解,或是去掉小括号能让代码更易于阅读,否则我们不应该去掉小括号。 我们没有理由假设读者能记住整个Java运算符优先级表。

4.8 具体结构

4.8.1 枚举类

枚举常量间用逗号隔开,换行可选。

没有方法和文档的枚举类可写成数组初始化的格式:

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

由于枚举类也是一个类,因此所有适用于其它类的格式规则也适用于枚举类。

4.8.2 变量声明

4.8.2.1 每次只声明一个变量

不要使用组合声明,比如int a, b;

4.8.2.2 需要时才声明,并尽快进行初始化

不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法),而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化,或者声明后尽快进行初始化。

4.8.3 数组

4.8.3.1 数组初始化:可写成块状结构

数组初始化可以写成块状结构,比如,下面的写法都是OK的:

new int[] {
  0, 1, 2, 3 
}

new int[] {
  0,
  1,
  2,
  3
}

new int[] {
  0, 1,
  2, 3
}

new int[]
    {0, 1, 2, 3}
4.8.3.2 非C风格的数组声明

中括号是类型的一部分:String[] args, 而非String args[]

4.8.4 switch语句

术语说明:switch块的大括号内是一个或多个语句组。每个语句组包含一个或多个switch标签(case FOO:default:),后面跟着一条或多条语句。

4.8.4.1 缩进

与其它块状结构一致,switch块中的内容缩进为2个空格。

每个switch标签后新起一行,再缩进2个空格,写下一条或多条语句。

4.8.4.2 Fall-through:注释

在一个switch块内,每个语句组要么通过break, continue, return或抛出异常来终止,要么通过一条注释来说明程序将继续执行到下一个语句组, 任何能表达这个意思的注释都是OK的(典型的是用// fall through)。这个特殊的注释并不需要在最后一个语句组(一般是default)中出现。示例:

switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}
4.8.4.3 default的情况要写出来

每个switch语句都包含一个default语句组,即使它什么代码也不包含。

4.8.5 注解(Annotations)

注解紧跟在文档块后面,应用于类、方法和构造函数,一个注解独占一行。这些换行不属于自动换行(第4.5节,自动换行),因此缩进级别不变。例如:

@Override
@Nullable
public String getNameIfPresent() { ... }

例外:单个的注解可以和签名的第一行出现在同一行。例如:

@Override public int hashCode() { ... }

应用于字段的注解紧随文档块出现,应用于字段的多个注解允许与字段出现在同一行。例如:

@Partial @Mock DataLoader loader;

参数和局部变量注解没有特定规则。

4.8.6 注释

4.8.6.1 块注释风格

块注释与其周围的代码在同一缩进级别。它们可以是/* ... */风格,也可以是// ...风格。对于多行的/* ... */注释,后续行必须从*开始, 并且与前一行的*对齐。以下示例注释都是OK的。

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

注释不要封闭在由星号或其它字符绘制的框架里。

Tip:在写多行注释时,如果你希望在必要时能重新换行(即注释像段落风格一样),那么使用/* ... */

4.8.7 Modifiers

类和成员的modifiers如果存在,则按Java语言规范中推荐的顺序出现。

public protected private abstract static final transient volatile synchronized native strictfp

命名约定

5.1 对所有标识符都通用的规则

标识符只能使用ASCII字母和数字,因此每个有效的标识符名称都能匹配正则表达式\w+

在Google其它编程语言风格中使用的特殊前缀或后缀,如name_mNames_namekName,在Java编程风格中都不再使用。

5.2 标识符类型的规则

5.2.1 包名

包名全部小写,连续的单词只是简单地连接起来,不使用下划线。

5.2.2 类名

类名都以UpperCamelCase风格编写。

类名通常是名词或名词短语,接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。

测试类的命名以它要测试的类的名称开始,以Test结束。例如,HashTestHashIntegrationTest

5.2.3 方法名

方法名都以lowerCamelCase风格编写。

方法名通常是动词或动词短语。

下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是:test<MethodUnderTest>_<state>,例如testPop_emptyStack。 并不存在唯一正确的方式来命名测试方法。

5.2.4 常量名

常量名命名模式为CONSTANT_CASE,全部字母大写,用下划线分隔单词。那,到底什么算是一个常量?

每个常量都是一个静态final字段,但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时, 考虑它是否真的感觉像是一个常量。例如,如果任何一个该实例的观测状态是可变的,则它几乎肯定不会是一个常量。 只是永远不打算改变对象一般是不够的,它要真的一直不变才能将它示为常量。

// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(',');  // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

这些名字通常是名词或名词短语。

5.2.5 非常量字段名

非常量字段名以lowerCamelCase风格编写。

这些名字通常是名词或名词短语。

5.2.6 参数名

参数名以lowerCamelCase风格编写。

参数应该避免用单个字符命名。

5.2.7 局部变量名

局部变量名以lowerCamelCase风格编写,比起其它类型的名称,局部变量名可以有更为宽松的缩写。

虽然缩写更宽松,但还是要避免用单字符进行命名,除了临时变量和循环变量。

即使局部变量是final和不可改变的,也不应该把它示为常量,自然也不能用常量的规则去命名它。

5.2.8 类型变量名

类型变量可用以下两种风格之一进行命名:

  • 单个的大写字母,后面可以跟一个数字(如:E, T, X, T2)。
  • 以类命名方式(5.2.2节),后面加个大写的T(如:RequestT, FooBarT)。

5.3 驼峰式命名法(CamelCase)

驼峰式命名法分大驼峰式命名法(UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。 有时,我们有不只一种合理的方式将一个英语词组转换成驼峰形式,如缩略语或不寻常的结构(例如”IPv6″或”iOS”)。Google指定了以下的转换方案。

名字从散文形式(prose form)开始:

  1. 把短语转换为纯ASCII码,并且移除任何单引号。例如:”Müller’s algorithm”将变成”Muellers algorithm”。
  2. 把这个结果切分成单词,在空格或其它标点符号(通常是连字符)处分割开。
    • 推荐:如果某个单词已经有了常用的驼峰表示形式,按它的组成将它分割开(如”AdWords”将分割成”ad words”)。 需要注意的是”iOS”并不是一个真正的驼峰表示形式,因此该推荐对它并不适用。
  3. 现在将所有字母都小写(包括缩写),然后将单词的第一个字母大写:
    • 每个单词的第一个字母都大写,来得到大驼峰式命名。
    • 除了第一个单词,每个单词的第一个字母都大写,来得到小驼峰式命名。
  4. 最后将所有的单词连接起来得到一个标识符。

示例:

Prose form                Correct               Incorrect
------------------------------------------------------------------
"XML HTTP request"        XmlHttpRequest        XMLHTTPRequest
"new customer ID"         newCustomerId         newCustomerID
"inner stopwatch"         innerStopwatch        innerStopWatch
"supports IPv6 on iOS?"   supportsIpv6OnIos     supportsIPv6OnIOS
"YouTube importer"        YouTubeImporter
                          YoutubeImporter*

加星号处表示可以,但不推荐。

Note:在英语中,某些带有连字符的单词形式不唯一。例如:”nonempty”和”non-empty”都是正确的,因此方法名checkNonemptycheckNonEmpty也都是正确的。

编程实践

6.1 @Override:能用则用

只要是合法的,就把@Override注解给用上。

6.2 捕获的异常:不能忽视

除了下面的例子,对捕获的异常不做响应是极少正确的。(典型的响应方式是打印日志,或者如果它被认为是不可能的,则把它当作一个AssertionError重新抛出。)

如果它确实是不需要在catch块中做任何响应,需要做注释加以说明(如下面的例子)。

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

例外:在测试中,如果一个捕获的异常被命名为expected,则它可以被不加注释地忽略。下面是一种非常常见的情形,用以确保所测试的方法会抛出一个期望中的异常, 因此在这里就没有必要加注释。

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 静态成员:使用类进行调用

使用类名调用静态的类成员,而不是具体某个对象或表达式。

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4 Finalizers: 禁用

极少会去重载Object.finalize

Tip:不要使用finalize。如果你非要使用它,请先仔细阅读和理解Effective Java 第7条款:“Avoid Finalizers”,然后不要使用它。

Javadoc

7.1 格式

7.1.1 一般形式

Javadoc块的基本格式如下所示:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

或者是以下单行形式:

/** An especially short bit of Javadoc. */

基本格式总是OK的。当整个Javadoc块能容纳于一行时(且没有Javadoc标记@XXX),可以使用单行形式。

7.1.2 段落

空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。 除了第一个段落,每个段落第一个单词前都有标签<p>,并且它和第一个单词间没有空格。

7.1.3 Javadoc标记

标准的Javadoc标记按以下顺序出现:@param@return@throws@deprecated, 前面这4种标记如果出现,描述都不能为空。 当描述无法在一行中容纳,连续行需要至少再缩进4个空格。

7.2 摘要片段

每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。

这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以A {@code Foo} is a...This method returns...开头, 它也不会是一个完整的祈使句,如Save the record...。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。

Tip:一个常见的错误是把简单的Javadoc写成/** @return the customer ID */,这是不正确的。它应该写成/** Returns the customer ID. */

7.3 哪里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc,以下是一些例外:

7.3.1 例外:不言自明的方法

对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了写“Returns the foo”,确实也没有什么值得写了。

单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。

Tip:如果有一些相关信息是需要读者了解的,那么以上的例外不应作为忽视这些信息的理由。例如,对于方法名getCanonicalName, 就不应该忽视文档说明,因为读者很可能不知道词语canonical name指的是什么。

7.3.2 例外:重载

如果一个方法重载了超类中的方法,那么Javadoc并非必需的。

7.3.3 可选的Javadoc

对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为, 那么这个注释应该写成Javadoc,这样更统一更友好。

后记

本文档翻译自Google Java Style, 作者@Hawstein

代码审查,也要天时地利人和

摘要:代码评审是指在软件开发过程中,通过对源代码进行系统性检查的过程。通常目的是查找系统缺陷,保证软件总体质量和提高开发者自身水平。这可不是一件简简单单的事。

当代码审查被广泛采用的时候,有很多种方法可以完成代码审查,团队争相使用最好的方法来完成代码审查已经是很常见的了。

斗胆的说一句:干这行的,你还是需要一点灵活性的。至于怎样执行代码审查程序取决以下几点:

人员

你的员工当中有多少开发人员,又有多少专业知识和人际水平都很丰富的审查人员?有的团队里只有一个高级开发人员,他们既是事必亲躬的代码员,又是代码审查员,可他们的所得和付出并不成正比。在一个小的团队里,资历高低一直是个问题,不管你试图完成什么任务。

地理位置

你的团队在哪?分散在各个区域?还是集中在一个大办公室里?审查代码需要集中注意力和及时反馈,当开发人员坐在一起的时候这两点就变得容易多了。如果你的团队不是同地协作,像“Over-the-shoulder”这样的代码审查过程就很难实现。

行业

所在的这个行业有什么规则和制度?在一个纪律严明的行业,你就必须遵守审计和报告的规则,这就意味着有一定的方法可以追踪到你的代码审查的频率和质量。如果你在安全性第一的行业,在代码审查的时候你同样需要关注并避免安全漏洞。

复杂性

你的代码有多复杂?一个审查员够了吗?还是需要多个具备不同专业知识的审查员?比方说,游戏开发可能涉及到许多复杂的逻辑来处理角色转换和场景跟踪,同时还要将特效动画和内存管理技术进行合并。因此,具有多个“Sets of eyes”的代码可能是审查像游戏开发这样复杂代码最有效的方法。

许多情况下,对于不同的项目会有不同的需求——你可能有多个团队正在搭建用户配置和需求都不一样的应用程序。一个你信得过的代码审查工具能够帮你完成高质量的代码审查流程,不管你使用的是什么方法。下面给出一些小建议,审查流程结合审查工具,这也许能解决你平时遇到的一些问题。

1. 加强交流

任何类型的审查过程,不管是代码审查,文献审查,或是性能审查,最好能够面对面的完成。当使用工具完成代码审查之后,开发人员在规定时间内提供语言反馈,如果不在同一地点,可以通过电话或视频对反馈的信息进行交流,因此,你也可以把代码审查过程看作是一次合作与指导的机会。

2. 发挥特长

如果正在审查的代码和其他区域的代码有接触点,或对安全,性能,延伸性等有影响,那就必须让更多的人检查代码以确保所有的分枝都已被考虑到位。在这种情况下,最好建立一个包含所有专业知识的人员库。这个工具可以帮助你甄别这些有用的人,并分配到需要的代码团队。你也可以利用这个工具收集所有人员的评论并分享给整个审查团队,这样大家可以相互学习。

3. 共享代码审查评论

使用工具的好处之一就是集中人员来审查相同的代码,将一组人集中到一起做小组评审,让每个人站在自己的角度思考代码里潜在的“问题”。每一个人都要对代码进行评论,并且允许团队成员看到相互之间的评论。能同时看到代码和别人的评论对整个团队来说是有很多好处的:

 

  • 没有重复的评论——第一个人说过的,第二个人就不能重复说。
  • 团队学习——能够看到其他人的评论,审查员可以相互学习。
  • 重复审查——有些时候一个审查员可以抓住另一个审查员的错误,这样就可以阻止错误被引入代码。

 

4. 审查指标

在代码审查过程中有一件事是肯定的,那就是使用工具指标。利用指标作为改进代码库的方法,这在代码审查过程具有很强的附加功能。工具可以告诉你哪些是最常见的错误,它们被引用在哪里,又在哪些地方重复过。同时可以根据在循环审查阶段,建立在缺陷记录基础上的质量问题,来判断哪些代码看上去易受攻击。在检查的时候就能阻止bugs,这明显是确保代码质量的最经济最高效的方法。metrics的使用还可以帮助开发人员找到哪些方面需要加强训练,以便以后开发出更好的代码。

5. 挖掘未来的代码审查员

你必须提升自己的的高度。因为要想识别出团队里的人哪些是可以进入审查员角色,就要花很大的精力和时间。理想情况下,你团队里的所有开发人员都能执行同行审查,这是合作程度和效率最高的方法,为了能够准时交付优质代码。但这需要花大量的时间和精力来打造这样一个高水平的团队。

代码审查很重要,审查过程中,审查人员和开发人员不是对立的关系,而是互助、沟通、协作和学习的过程。团队形成互助、互学的气氛,既能互相增长团队的知识和经验,还能把产品做得更好。Code Review的核心是:互助,沟通,协作,学习的过程,这是一个美妙而享受的过程,是跨越需求分析、架构设计、编码等各阶段的过程。(编译/薛梁 责编/夏梦竹)

原文:smartbear

http://www.csdn.net/article/2013-06-20/2815921-Making-Code-Review-Work

IT旅途——程序员面试经验分享

http://www.csdn.net/article/2013-05-09/2815198-programmer-interview

摘要:本文从IT人员的角度,一起分享面试道路上的坎坷。文章汇集几个知名公司的面试题,从出题的角度到分析问题的方法到解决问题较为全面的讲解面试题目,以供读者参考。

面试是职场的永恒话题,如何在职场面试中脱颖而出,获得心仪职位?这里搜集了关于面试经验的热文,其中汇集了阿里巴巴、百度、微软几个知名公司的面试题以及部分答题方法、技巧、面试的心得体会,供读者参考。
[1] 教你如何迅速秒杀掉:99%的海量数据处理面试题

本文分成两部分。第一部分、从set/map谈到hashtable/hash_map/hash_set,简要介绍下set/map/multiset/multimap,及hash_set/hash_map/hash_multiset/hash_multimap之区别(万丈高楼平地起,基础最重要),而本文第二部分,则针对上述那6种方法模式结合对应的海量数据处理面试题分别具体阐述。

[2] 百度最新面试题集锦

最新的面试题集有时也代表公司近来的研发方向甚至科研趋势,这里,博主收集了一些百度最新的面试题集,其中有较为有趣的试题,

比如:
蚂蚁爬杆问题:
有一根27厘米长的细木杆,在第3厘米,7厘米,11厘米,17厘米,23厘米这五个位置上各有一只蚂蚁,木杆很细,不能同时通过两只蚂蚁,开始时,蚂蚁的头朝向左还是右是任意的,他们只会朝前走或掉头,但不会后退,当两只蚂蚁相遇后,蚂蚁会同时掉头朝反方向走,假设蚂蚁们每秒钟可以走1厘米的距离。求所有蚂蚁都离开木杆的最小时间和最大时间。
答案:
两只蚂蚁相遇后,各自掉头朝相反方向走。如果我们不考虑每个蚂蚁的具体身份,这和 两只蚂蚁相遇后,打个招呼继续向前走没有什么区别。
所有蚂蚁都离开木杆的最小时间为
max(min(3,27-3),min(7,27-7), min(11,27-11), min(17,27-17),min(23,27-23))=11
所有蚂蚁都离开木杆的最大时间为
max(max(3,27-3),max(7,27-7), max(11,27-11), max(17,27-17),max(23,27-23))=24

三个警察和三个囚徒的过河问题:
三个警察和三个囚徒共同旅行。一条河挡住了去路,河边有一条船,但是每次只能载2人。存在如下的危险:无论在河的哪边,当囚徒人数多于警察的人数时,将有警察被囚徒杀死。问题:请问如何确定渡河方案,才能保证6人安全无损的过河。
答案:
第一次:两囚徒同过,回一囚徒
第二次:两囚徒同过,回一囚徒
第三次:两警察同过,回一囚徒一警察(此时对岸还剩下一囚徒一警察,是安全状态)
第四次:两警察同过,回一囚徒(此时对岸有3个警察,是安全状态)
[3] 阿里巴巴的面试

博主在文中指出,进入技术面试之前,先要做一套相应的试题,这里面涉及到平常不怎么注意的问题:
一是没有定义访问范围的构造函数,前面未加public、protected或private限制等,默认protected,编译会报错;

二是页面中定义两个同名的JS函数,调用会是什么结果,后面尝试了一下不报错,会调用第二个方法;
[4]苹果面试8大难题及答案

苹果这样的公司通常会在面试过程中向求职者抛出一些逻辑的问题来考研面试者,所以,如果你对进入苹果感兴趣,或者只是对逻辑问题感兴趣,这些面试难题值得你仔细研究。

比如:
“逻辑学家们围成一圈坐着,他们的额头上面画有数字……”又来一个逻辑学家围成一圈的问题,这次是这样的,三个拥有完美逻辑推理能力的人围成一圈坐在一个房间里,每个人的额头上都画着一个大于0的数字,三个人的数字各不相同,每个人都看得见其他两个人的数字,看不见自己的。
这三个数字的情况是,其中一个数字是其他两个数字的和,已知的情况还有,其中一个逻辑学家的数字是20,一个是30。游戏组织者从这三个逻辑学家后面走过,并问三个人各自额头上的数字是什么。但第一轮每个逻辑学家都回答他们无法推测自己的数字是什么。游戏组织者只好进行第二轮的发问,这是为什么?你能据此猜出三个逻辑学家的数字吗?

[5]12个有趣的C语言面试题

12个C语言面试题,涉及指针、进程、运算、结构体、函数、内存等内容,比如:
内存泄露:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
1.  #include<stdio.h>
2.  
3.  void func(void)
4.  {
5.      printf("\n Cleanup function called \n");
6.      return;
7.  }
8.  
9.  int main(void)
10. {
11.     int i = 0;
12. 
13.     atexit(func);
14. 
15.     for(;i<0xffffff;i++);
16. 
17.     _exit(0);
18. }

这是因为_exit()函数的使用,该函数并没有调用atexit()等函数清理。如果使用atexit()就应当使用exit()或者“return”与之相配合。

[6]Java程序员面试中的多线程问题

这篇文章收集了 Java 线程方面一些典型的问题,

比如:
为什么需要 run ()和 start ()方法,我们可以只用 run ()方法来完成任务吗?
我们需要 run ()&start ()这两个方法是因为 JVM 创建一个单独的线程不同于普通方法的调用,所以这项工作由线程的 start 方法来完成,start 由本地方法实现,需要显示地被调用,使用这俩个方法的另外一个好处是任何一个对象都可以作为线程运行,只要实现了 Runnable 接口,这就避免因继承了 Thread 类而造成的 Java 的多继承问题。

[7]设计模式大集锦 程序员面试全攻略

无论你是参与Java面试还是C#面试,设计模式和软件设计问题在程序员面试中是必不可少的一部分。本文总结了在各种面试过程中经常被提及的一些设计问题。文中分为两部分,一类为初学者,另一类专为中高级技术人员准备。

[8]如何在面试时写出高质量的代码

如何在面试时能写出高质量的代码,是很多程序员关心的问题。作者总结自己多年面试他人以及被他人面试的经验,发现应聘者可以从代码的规范性、完整性和鲁棒性三个方面提高代码的质量。

[9]编程技术面试的五大要点

编程面试是程序员面试过程中最为重要的一个环节,其中主要关注应聘者五种素质:

(1)扎实的基础知识

(2)能写高质量的代码

(3)分析问题时思路清晰

(4)能优化时间效率和空间效率

(5)具备包括学习能力、沟通能力、发散思维能力等在内的综合能力。

[10] 谈谈对于技术面试的心得体验

博主在文中谈到,一个公司的技术面试需要有良好的经验传承,不光光只是留来一些题库;也不光光是一句要相互尊重,你代表公司的形象;更重要的如何去主导一场面试,全面、准确的了解对方的能力。一般情况下,软件公司招人总会对这三个方面的能力做一下考核,一是编程语言,二是数据结构与算法,三是系统设计。

延伸阅读: 编程技术面试的五大要点

华为的JAVA面试题及答案(部分)

IT求职经验总结——面试和准备策略

程序员成熟的标志

http://www.cnblogs.com/n216/archive/2011/05/16/2047327.html

程序员在经历了若干年编程工作之后,很想知道自己水平到底如何?自己是否已经成为成熟的程序员?虽然程序员会对自己有一个自我评价,但是,自己的评价和社会的评价、专业的评价会有差异,所以程序员自己并不能肯定这个评价。现实中,除了各种证书之外,很少有人会专门给出一个程序员的成熟度的评价。人们往往是偶发性地就事论事地对程序员的工作作出好与不好,行与不行的评论。因此,程序员对此感到很茫然,不知道要从那些方面去评价自己的能力。

一个程序员到底成熟不成熟,我想从以下几个方面谈谈自己的看法。

1、技术标志

如果程序员不会编程序那决不是程序员,程序员至少要掌握一门程序设计语言,要能够用这种语言去编写程序去解决他想解决的问题。但是,成熟的程序员往往掌握不止一种程序语言,三到四种语言的掌握是必须的,一种二种语言的精通也是必须的。

除了从掌握程序设计语言个数之外,我们还可以从其他几个方面去看看程序员在技术上水平。例如,函数编写能力(命名、格式、大小、分类、参数、复用等),面向过程的能力,面向对象的能力,数据库技术能力,效率处理能力,安全处理能力,网络处理能力,软件构架能力,人机交互能力,通用软件能力,软件文档能力等等。尤其是面向对象技术的掌握和运用,以及面向服务的技术都是成熟程序员所必需掌握的。

    2、时间标志

虽然程序员的天资、素质、基础知识各不相同,所经历的工作内容以及环境也不相同,但是,时间也是程序员成熟程度的标志之一。一般程序员需要经过三到五年的时间才能日趋成熟。其中入门需要一年,成长需要两年。这是我经过长期观察得到平均数据。我并不认为成熟时间越短程序员就越聪明,就越了不起。享受每个阶段充分的时间,会让自己成长更加充实、更加成熟。当然,也有超期而不成熟的情况,这也是很正常的。

    3、项目标志

程序员的社会性是程序员成熟的标志之一。没有参加过项目的程序员,程序编得再好,只能是纯程序类的程序员,是一个孤独的高手,是一种个人型的程序员,远没有成熟。项目作为社会性活动,体现了项目的社会价值。所以项目能力也是程序员成熟的重要标志之一:项目能力包括参加项目的个数、项目的大小、在项目中承担的角色等等。就项目承担的角色而言,主持开发(项目经理)3个以上项目是必须的,这是一个必要条件。一个程序员如果没有主持过开发,无论参加过多少项目的开发,无论是在程序编写或项目设计上发挥了多大的作用,是很难被称之为成熟的,因为项目的组织、协调和管理是反映一个程序员成熟程度的又一个标志。就如同一个程序员能参与过10个以上大大小小的项目或能参加或能主持两个以上大型项目的开发,其成熟程度是可以信赖的。若低于此数,则说明程序员离成熟还有相当的空间。“我们在项目中成长”可见项目对于程序员的意义是多么的巨大。

另外,一般程序员只是为一个企业客户进行开发一个或多个项目,或同行业的企开发项目,如果程序员能够如果程序员能够开发过多个行业的项目,其成熟度要比一般人要高一些。

    4、思维标志

幼稚和成熟在思维方式上还是有很明显的区别的。就程序员而言,不成熟的程序员逻辑性不强,程序编得没有条理,即使程序员自己进行了解释也没人能看懂。而成熟的程序员应该具有很强的逻辑性,程序编得井井有条,不用解释别人也能看得懂。这种逻辑性还体现在软件的构架设计、数据库设计、算法设计等多个方面。程序员通过全集子集概念、时间概念、顺序概念、重点非重点概念等对各种事物进行逻辑分析。例如,以顺序概念为例,不成熟的程序员往往会采用自底向上的思维方式来开发程序。他们先考虑程序的具体实现,然后再考虑功能设计、最后考虑构架设计。而成熟的程序员则采用自顶向下思维方式,先考虑构架设计、再考虑功能设计、最后才考虑编程的具体实现。前者思维方式主要是出于工作惯性,只适合入门阶段,而后者思维方式反映了后者的进步,适用于各种项目开发或大型项目的开发。

除了在思维内容上的逻辑性之外,程序员还应该处理好动脑和动手的关系。重视思维本身就是一种成熟的标志。成熟的程序员的思考时间要大于动手编程时间,想好之后只要一次就编程成功,而不成熟的程序员往往动手编程时间要远大于思考时间,而且是边做边想,通过反复来逼近最终目标。

另外,在思维范围上,成熟的程序员要比普通的程序员有更开放视野。他们更容易去接受新的东西,更容易不受各种约束去考虑问题,更勇于去挑战自己和高手。

 5、与人交往

很多人认为程序员是和计算机打交道的行业。这只是这个职业的特点。但是,只要是工作必然就是一种社会劳动。而社会劳动则必须和人进行交流和沟通。尽管程序员的劳动工具是计算机,但并不意味着程序员只想着这个工具。从这个工具的下游来看,程序员还是要考虑用这个劳动工具生产出来的软件产品是否有人购买,是否有人使用,是否运行正常,从这个工具的上游来看,是谁让程序员了解设计方案的,是谁让程序员编程序的,是谁让程序员程序通过验收的等等。因此程序员在软件制作各个环节都会与其他人打交道。只有和人进行有效的交流和沟通我们的工作才能进行下去才能做的更好。

如果一个程序员还沉浸在个人劳动的意境之中,对外界持有冷漠、无奈、恐惧的心理,内心里不愿意和外界打交道,无论自己感觉自己的技术水平有多高,还是一个不成熟的程序员。而成熟的程序员一定是特别重视与人的交往,无论是上级领导、外部客户、项目经理、团队同伴这些与自身工作密切相关的人还是那些非同单位同行朋友、网友等他们都会认真去听取别人的阐述、要求、意见、建议、反馈等。从中得到更多的工作上的、技术上的、生活上的好的想法,以便自己参考和吸收。与此同时,与人交往也反映你有好的想法和好的技术水平交流出去,而这些想法和技术水平也是你成熟度一种反映。那些没有想法和技术水平的程序员的确是怕和别人交流的。

与人交流的有两个基本能力,一个是理解能力,一个是表达能力。两者缺一不可。例如,有的程序员理解能力差,不能理解项目经理提出的要求,有的程序员表达能力差,无逻辑,无重点,啰里啰唆,让别人不知所云。这都是不成熟的表现。

   6、别人评价

别人的评价尤其是单位同事以及对自己工作情况比较了解的人对自己的评价是有参考价值的。一般而言,评价差的,一定是不行的,是不成熟的。评价好的要看情况而定,单位同事对人的评价会从两个方面来考虑,一个是这个人的为人情况,一个是这个人的工作能力。如果两者都不错,我们有理由认为这个程序员是成熟的。反之,无论是工作能力强,但为人不好,为人很好,工作能力不强,我看都不能算一个成熟的程序员。

所以,程序员要注重别人对自己的评价,在提高自己技术水平的同时,学会做人,做好人,学会与他人分享,这样别人才会给自己更好的评价。

无视别人评价其实,也是一种不成熟的表现。只有自己感觉好,大家感觉好,那才是真的好。

其实,别人的评价如果仅限于自己单位的话,恐怕这种评价的价值会打折扣,如果这个单位技术人员的人数很少,水平普遍很低,即使你鹤立鸡群,大家对你的评价很好,但是,你和其他公司和单位的程序员来比,你真的不一定的成熟。所以,我说别人的评价仅仅是一个参考。

   7、收入标志

收入也是成熟程序员一个参考标志。收入的大小往往是对程序员社会价值的认可度,表明程序员的劳动值这个价钱。一般而言,成熟的程序员能够挣得软件业平均收入的中上水平,或者在一个单位或部门中能够挣得比80%左右员工要高的收入。而刚参加工作不久的程序员收入应该与其相差很大的。另外,单位的项目奖金发放也可以看出程序员在项目中的地位和作用。

现实中,我们知道程序员的收入和其付出是不是正比的,而且,越是能力强的、贡献大的程序员,可能不一定比那些不如其它能力不如他的程序员高出许多。这不是软件行业的通病,几乎所有行业都存在这种情况。通过分析我们认为程序员成熟度应该是和其收入高低挂钩的。如果,我们知道我们能力和贡献大大超出我们的收入,我们就有理由向上级领导提出自己的收入要求。

   8、心理素质

程序员常常面对各种各样的成功和失败,尤其是失败更是多于成功,这也是程序员这个职业特点之一。以编程为例,几乎没有一个人一次就能把程序给编好的,它总是要遇到各种语法错误,总要遇到各种遗漏,一个程序要反复多次修改调试才能完好。有的程序员因找不出来程序的bug,束手无措,哀声叹气,心里极其不爽。以工作为例,有的程序员因工作进度和程序出错常常受到别人的批评和指责,心里极其不满,认为批评人不了解造成这个结果的客观原因,批评错了人。从而对人产生意见,甚至对工作造成了影响。面对失败和挫折,成熟的程序员会坦然面对:编程时出现问题不可怕,有什么问题就解决问题,解决不了的问题可以想其他方法进行解决,不在一棵树上吊死。面对别人的批评和指责,首先从自身查问题,是自己的问题,那就要主动承担责任,并尽快改正。不是自己的问题,应该换位思考,理解批评人的焦急心态,并找机会给予说明。良好的心理素质在面对困难和挫折的时候,就会很坦然,很坚强,很自信。

程序员也会面对成功的。有些程序员因开发了某个项目,因编写了某个程序而感觉良好,在不自觉中表现出我最牛,我最好的样子,面对他人夸夸其谈,而对其他人不屑一顾。而更有甚者并其无成果,表现平平,却依然会摆出一个高手的样子,有的仅仅参与了某个项目,而且不是项目主要开发者,却会贪天之功,归其所有,好像这个项目是他主持开发的。这些其实也是心理素质不成熟的另一种表现。成熟的程序员面对成功并不会感觉到高人一等,该是自己的功劳就是自己的功劳,该是别人的功劳就是别人的功劳,即使自己比别人水平高出许多,他还是在想还有更高的技术顶峰等待攀登,不可自傲,看到别人取得的成绩首先感到去祝贺,然后去学习,而不是心怀嫉妒,从中挑刺,尽量贬低。

良好的心理素质使得程序员更加理性地处理好各种成功和失败带来的各种问题,更有利于程序员超越自我,以平常之心去迎接更大的挑战。

当然一个程序员是否成熟是一个仁者见仁,智者见智的话题。有的人强调程序员的个人能力方面,有的人强调是程序员的社会能力方面。我认为从以上8个方面综合地去评判一个程序员是否成熟应该能说明些问题了。我们标志成熟,一个目的是对程序员前面成长过程给与一个肯定和鼓励,让程序员认清自己的所处的阶段,让自信找出依据。另外一个目的是对程序员未来成长提出更高的要求。走向优秀是程序员面临的更大的挑战。

高效代码审查的十个经验

http://kb.cnblogs.com/page/163000/

  代码审查(Code Review)是软件开发中常用的手段,和QA测试相比,它更容易发现和架构以及时序相关等较难发现的问题,还可以帮助团队成员提高编程技能,统一编程风格等。

  1. 代码审查要求团队有良好的文化

团队需要认识到代码审查是为了提高整个团队的能力,而不是针对个体设置的检查“关卡”。

“A的代码有个bug被B发现,所以A能力不行,B能力更好”,这一类的陷阱很容易被扩散从而影响团队内部的协作,因此需要避免。

另外,代码审查本身可以提高开发者的能力,让其从自身犯过的错误中学习,从他人的思路中学习。如果开发者对这个流程有抵触或者反感,这个目的就达不到。

2. 谨慎的使用审查中问题的发现率作为考评标准

  在代码审查中如果发现问题,对于问题的发现者来说这是好事,应该予以鼓励。但对于被发现者,我们不主张使用这个方式予以惩罚。软件开发中bug在所难免,过度苛求本身有悖常理。更糟的是,如果造成参与者怕承担责任,不愿意在审查中指出问题,代码审查就没有任何的价值和意义。

3. 控制每次审查的代码数量

根据smartbear在思科所作的调查,每次审查200行-400行的代码效果最好。每次试图审查的代码过多,发现问题的能力就会下降,具体的比例关系如下图所示:

  我们在实践中发现,随着开发平台和开发语言的不同,最优的代码审查量有所不同。但是限制每次审查的数量确实非常必要,因为这个过程是高强度的脑力密集型活动。时间一长,代码在审查者眼里只是字母,无任何逻辑联系,自然不会有太多的产出。

4. 带着问题去进行审查

我们在每次代码审查中,要求审查者利用自身的经验先思考可能会碰到的问题,然后通过审查工作验证这些问题是否已经解决。一个窍门是,从用户可见的功能出发,假设一个比较复杂的使用场景,在代码阅读中验证这个使用场景是否能够正确工作。

使用这个技巧,可以让审查者有代入感,真正的沉浸入代码中,提高效率。大家都知道看武侠小说不容易瞌睡,而看专业书容易瞌睡,原因就是武侠小说更容易产生代入感。

有的研究建议每次树立目标,控制单位时间内审核的代码数量。这个方法在我们的实践中显得很机械和流程化,不如上面的方法效果好。

5. 所有的问题和修改,必须由原作者进行确认

如果在审查中发现问题,务必由原作者进行确认。

这样做有两个目的:

(1) 确认问题确实存在,保证问题被解决。

(2) 让原作者了解问题和不足,帮助其成长。

有些时候为了追求效率,有经验的审查者更倾向于直接修改代码乃至重构所有代码,但这样不利于提高团队效率,并且会增加因为重构引入新bug的几率,通常情况下我们不予鼓励。

6. 利用代码审查激活个体“能动性”

即使项目进度比较紧张,无法完全的进行代码审查,至少也要进行部分代码的审查,此时随即抽取一些关键部分是个不错的办法。

背后的逻辑是,软件开发是非常有创造性的工作,开发者都有强烈的自我驱动性和自我实现的要求。让开发者知道他写的任何代码都可能被其他人阅读和审察,可以促使开发者集中注意力,尤其是避免将质量糟糕,乃至有低级错误的代码提交给同伴审查。开源软件也很好的利用了这种心态来提高代码质量。

7. 在非正式,轻松的环境下进行代码审查

如前所述,代码审查是一个脑力密集型的工作。参与者需要在比较轻松的环境下进行该工作。因此,我们认为像某些实践中建议的那样,以会议的形式进行代码审查效果并不好,不仅因为长时间的会议容易让效率低下,更因为会议上可能出现的争议和思考不利于进行如此复杂的工作。

8. 提交代码前自我审查,添加对代码的说明

所有团队成员在提交代码给其他成员审查前,必须先进行一次审查。这次自我修正形式的审查除了检查代码的正确性以外,还可以完成如下的工作:

(1) 对代码添加注释,说明本次修改背后的原因,方便其他人进行审查。

(2) 修正编码风格,尤其是一些关键数据结构和方法的命名,提高代码的可读性。

(3) 从全局审视设计,是否完整的考虑了所有情景。在实现之前做的设计如果存在考虑不周的情况,这个阶段可以很好的进行补救。

我们在实践中发现,即使只有原作者进行代码审查,仍然可以很好的提高代码质量。

9. 实现中记录笔记可以很好的提高问题发现率

成员在编码的时候应做随手记录,包括在代码中用注释的方式表示,或者记录简单的个人文档,这样做有几个好处:

(1) 避免遗漏。在编码时将考虑到的任何问题都记录下来,在审查阶段再次检查这些问题都确认解决。

(2) 根据研究,每个人都习惯犯一些重复性的错误。这类问题在编码是记录下来,可以在审查的时候用作检查的依据。

(3) 在反复记录笔记并在审查中发现类似的问题后,该类问题出现率会显著下降

10. 使用好的工具进行轻量级的代码审查

“工欲善其事,必先利其器”。我们使用的是bitbucket提供的代码托管服务。

每个团队成员独立开发功能,然后利用Pull Request的形式将代码提交给审查者。复审者可以很方便在网页上阅读代码,添加评论等,然后原作者会自动收到邮件提醒,对审阅的意见进行讨论。

即使团队成员分布在天南海北,利用bitbucket提供的工具也能很好的进行代码审查。

什么是整洁的代码(Clean Code)?

http://www.iteye.com/news/26838

什么样的代码才是真正好的、整洁的代码?来看看大牛们怎么说。 

Bjarne Stroustrup,C++之父:

引用
我喜欢优雅、高效的代码:

  • 逻辑应该是清晰的,bug难以隐藏;
  • 依赖最少,易于维护;
  • 错误处理完全根据一个明确的策略;
  • 性能接近最佳化,避免代码混乱和无原则的优化;
  • 整洁的代码只做一件事。

Grady Booch,《面向对象分析与设计》作者:

引用
  • 整洁的代码是简单、直接的;
  • 整洁的代码,读起来像是一篇写得很好的散文;
  • 整洁的代码永远不会掩盖设计者的意图,而是具有少量的抽象和清晰的控制行。

Dave Thomas,OTI公司创始人,Eclipse战略教父:

引用
  • 整洁的代码可以被除了原作者之外的其他开发者阅读和改善;
  • 具备单元测试和验收测试;
  • 有一个有意义的名字;
  • 使用一种方式来做一件事情;
  • 最少的依赖,并明确定义;
  • 提供了一个清晰的、最小的API;
  • 应该根据语言特性,在代码中单独显示必要的信息,而不是所有的信息。

Michael Feathers,《修改代码的艺术》作者:

引用
  • 整洁的代码看起来总是像很在乎代码质量的人写的;
  • 没有明显的需要改善的地方;
  • 代码的作者似乎考虑到了所有的事情。

Ward Cunningham,Wiki和Fit创始人,极限编程联合创始人,Smalltalk和面向对象的思想领袖:

引用
  • 当你读代码时,你发现每个程序都如你期待的那样
  • 你可以称之为漂亮的代码
  • 代码完美展现了该编程语言的设计目的

总之,整洁的代码的特点:

  • 容易与其他人协作(简单、意图明确、良好的抽象、不出意料、合适的名称)
  • 针对现实世界,比如,有一个清晰的错误处理策略
  • 代码作者显然很关心软件和其他开发者(针对双方的可读性和可维护性)
  • 最小化(做一件事,最小的依赖)
  • 以最合适的方式解决问题

编写超级可读代码的15个最佳实践

http://blog.csdn.net/hfahe/article/details/6303585

译自:http://net.tutsplus.com/tutorials/html-css-techniques/top-15-best-practices-for-writing-super-readable-code/

译者:蒋宇捷(转载请标明出处-http://blog.csdn.net/hfahe)

 

       一月两次,我们重温Nettuts历史上读者最喜欢的文章。

代码可读性是一个计算机编程世界的普遍主题。它是我们作为开发者第一件学习的事情。这篇文章将阐述编写可读性代码十五个最重要的最佳实践。


1 – 注释和文档

集成开发环境IDE在过去的短短几年里走过了很长的路。它使得注释代码比以前更加有用。依照特定标准书写的注释允许IDE和其他工具通过不同的方式来使用它们。

考虑如下示例:

 

我在函数定义中添加的注释可以在调用它的地方看到,即便是在其他文件中。

这里是我另外一个从第三方库中调用函数的例子:

 

在这些特殊的例子中,使用的注释(或者文档)类型基于PHPDoc,IDE是Aptana


2 – 一致的排版

我假定你已经知道了你必须要缩进你的代码。然而,保持排版样式一致仍然是一个好主意。

这里有不止一种方式来进行代码排版。

第一种:

 

[c-sharp] view plaincopy
  1. function foo() {
  2.     if ($maybe) {
  3.         do_it_now();
  4.         again();
  5.     } else {
  6.         abort_mission();
  7.     }
  8.     finalize();
  9. }

 

第二种:

 

[c-sharp] view plaincopy

  1. function foo()
  2. {
  3.     if ($maybe)
  4.     {
  5.         do_it_now();
  6.         again();
  7.     }
  8.     else
  9.     {
  10.         abort_mission();
  11.     }
  12.     finalize();
  13. }

 

第三种:

 

[c-sharp] view plaincopy

  1. function foo()
  2. {   if ($maybe)
  3.     {   do_it_now();
  4.         again();
  5.     }
  6.     else
  7.     {   abort_mission();
  8.     }
  9.     finalize();
  10. }

 

我曾经使用第二种样式但是最近换为第一种。但是这仅仅只代表了一种偏爱。这里并没有每个人必须要遵守的“最好的”样式。事实上,最佳的样式,就是一致的样式。如果你是一个小组的一部分或者你在为一个项目贡献代码,你必须依照这个项目之前使用的样式。

排版的样式总不是完全和另外一个不同。有时,它们混合了多种不同的规则。例如,按照PEAR编码标准,前括弧“{”和控制结构在同一行上,但是在功能定义后放在第二行上。

PEAR样式:

 

[c-sharp] view plaincopy

  1. function foo()
  2. {                     // placed on the next line
  3.     if ($maybe) {     // placed on the same line
  4.         do_it_now();
  5.         again();
  6.     } else {
  7.         abort_mission();
  8.     }
  9.     finalize();
  10. }

 

同时注意它们使用4个空格而不是Tab来缩进。

这里有一个维基百科的文章,里面有许多不同排版样式的例子。


3 – 避免显而易见的注释

为代码添加注释是效果显著的;但是,它可能太过或者只是多余的文本。像如下例子:

 

[c-sharp] view plaincopy

  1. // get the country code
  2. $country_code = get_country_code($_SERVER[‘REMOTE_ADDR’]);
  3. // if country code is US
  4. if ($country_code == ‘US’) {
  5.     // display the form input for state
  6.     echo form_input_state();
  7. }

 

如果注释内容都是显而易见的,它们并没有提高工作效率。如果你必须要注释这些代码,你可以简单的把它们合并在一行:

 

[c-sharp] view plaincopy

  1. // display state selection for US users
  2. $country_code = get_country_code($_SERVER[‘REMOTE_ADDR’]);
  3. if ($country_code == ‘US’) {
  4.     echo form_input_state();
  5. }

 


4 – 代码分组

确定的任务多半需要多行代码。使用一些空白将这些任务的代码分隔为几段是一个好主意。

这是一个简单的示例:

 

[c-sharp] view plaincopy

  1. // get list of forums
  2. $forums = array();
  3. $r = mysql_query(“SELECT id, name, description FROM forums”);
  4. while ($d = mysql_fetch_assoc($r)) {
  5.     $forums []= $d;
  6. }
  7. // load the templates
  8. load_template(‘header’);
  9. load_template(‘forum_list’,$forums);
  10. load_template(‘footer’);

 

在每一段之前添加注释也增强了视觉上的分隔。


5 – 命名的一致性

PHP有些时候在遵守命名一致性方面有很大问题:

  • strops()和str_split()
  • imagetypes()和image_type_to_extension()

首先,这些命名必须有单词的分界线。有两种流行的选择:

  • 骆驼命名法:除了第一个单词外,每个单词的第一个字符大写。
  • 下划线命名法: 单词间采用下划线,例如mysql_real_escape_string()。

像我之前提到的一样,采用不同的命名选择会创建和排版样式类似的情形。如果一个已有的项目遵照一个确定的习惯,你必须遵守它。同时,某些语言平台倾向于使用特定的命名规则。例如Java里,大多数代码使用骆驼命名法;在PHP里大多采用下划线命名法。

它们也可以混用。一些开发者喜欢在程序函数和类名上使用下划线命名,但是在类方法名上使用骆驼命名。

 

[c-sharp] view plaincopy

  1. class Foo_Bar {
  2.     public function someDummyMethod() {
  3.     }
  4. }
  5. function procedural_function_name() {
  6. }

 

所以,没有明显的“最好的”样式,只需要保持一致。


6 – DRY原则

DRY即不要重复你自己。也被称为DIE:重复是恶魔。

这个原则规定:

      “在一个系统里每一个知识的片段必须有一个单一、明确、权威的表现。”

大多数应用程序(或者通常的计算机)的目的是让重复的任务自动化。这个原则在所有的代码,即使Web程序中也应该保持。代码的相同片段不应该多次重复。

例如,大多数Web程序由许多页面组成。这些页面很可能包含相同的元素。页头和页脚经常符合这个条件。复制和粘贴这些页头和页尾到每一个页面中不是一个好主意。这是Jeffrey Way解释如何在CodeIgniter里创建模版的链接

 

[c-sharp] view plaincopy

  1. $this->load->view(‘includes/header’);
  2. $this->load->view($main_content);
  3. $this->load->view(‘includes/footer’);

 


7 – 避免过深的嵌套

太多层的嵌套会造成代码阅读和跟踪困难。

 

[c-sharp] view plaincopy

  1. function do_stuff() {
  2. // …
  3.     if (is_writable($folder)) {
  4.         if ($fp = fopen($file_path,’w’)) {
  5.             if ($stuff = get_some_stuff()) {
  6.                 if (fwrite($fp,$stuff)) {
  7.                     // …
  8.                 } else {
  9.                     return false;
  10.                 }
  11.             } else {
  12.                 return false;
  13.             }
  14.         } else {
  15.             return false;
  16.         }
  17.     } else {
  18.         return false;
  19.     }
  20. }

 

为了可读性,通常需要修改代码来减少嵌套的层数。

 

[c-sharp] view plaincopy

  1. function do_stuff() {
  2. // …
  3.     if (!is_writable($folder)) {
  4.         return false;
  5.     }
  6.     if (!$fp = fopen($file_path,’w’)) {
  7.         return false;
  8.     }
  9.     if (!$stuff = get_some_stuff()) {
  10.         return false;
  11.     }
  12.     if (fwrite($fp,$stuff)) {
  13.         // …
  14.     } else {
  15.         return false;
  16.     }
  17. }

 


8 – 减少行的长度

我们的眼睛对于阅读高和窄的文本列更感觉舒适。这就是为什么报纸文章看起来像如下样子的原因:

 

避免在一行上编写过长的代码是一个最佳实践。

 

[c-sharp] view plaincopy
  1. // bad
  2. $my_email->set_from(‘test@email.com’)->add_to(‘programming@gmail.com’)->set_subject(‘Methods Chained’)->set_body(‘Some long message’)->send();
  3. // good
  4. $my_email
  5.     ->set_from(‘test@email.com’)
  6.     ->add_to(‘programming@gmail.com’)
  7.     ->set_subject(‘Methods Chained’)
  8.     ->set_body(‘Some long message’)
  9.     ->send();
  10. // bad
  11. $query = “SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = ‘123’”;
  12. // good
  13. $query = “SELECT id, username, first_name, last_name, status
  14.     FROM users
  15.     LEFT JOIN user_posts USING(users.id, user_posts.user_id)
  16.     WHERE post_id = ‘123’”;

 

同时,如果任何人想要在例如Vim这样的终端窗口中阅读代码,限制每一行的长度在80个字符以内是一个好主意。


 

9 – 代码结构

理论上,你可以将整个应用代码写在一个文件里。但是对于阅读和维护来说是一个噩梦。

在我的第一个编程项目中,我知道创建“包含文件”的含义。但是,我并没有好好进行组织。我创建了一个“inc”文件夹,放置了两个文件:db.php、functions.php。当程序变大时,functions文件也变得越来越大并难以维护。

最好的方法之一是采用框架或者模仿它们的文件夹结构。下面是CodeIgniter的文件结构:

 


10 – 统一的临时变量名

通常,变量名应该是描述性的并且包含一个或者更多的单词。但是,这对临时变量来说并不是必须的。它们可以短到只有一个单独字符。

最佳实践是:对于有同样职责临时变量采用统一的命名。这里有一些我倾向于在代码里使用的例子:

 

[c-sharp] view plaincopy
  1. // $i for loop counters
  2. for ($i = 0; $i < 100; $i++) {
  3.     // $j for the nested loop counters
  4.     for ($j = 0; $j < 100; $j++) {
  5.     }
  6. }
  7. // $ret for return variables
  8. function foo() {
  9.     $ret[‘bar’] = get_bar();
  10.     $ret[‘stuff’] = get_stuff();
  11.     return $ret;
  12. }
  13. // $k and $v in foreach
  14. foreach ($some_array as $k => $v) {
  15. }
  16. // $q, $r and $d for mysql
  17. $q = “SELECT * FROM table”;
  18. $r = mysql_query($q);
  19. while ($d = mysql_fetch_assocr($r)) {
  20. }
  21. // $fp for file pointers
  22. $fp = fopen(‘file.txt’,’w’);

 


 

11 – SQL关键词大写

数据库交互对于大多数Web应用来说是很大一个组成部分。如果你正在编写SQL查询,尽量保持它们可读。

即使SQL关键词和函数名是大小写无关的,大写来将它们从表名和列名中区分出来是一个通用的实践。

 

[c-sharp] view plaincopy

  1. SELECT id, username FROM user;
  2. UPDATE user SET last_login = NOW()
  3. WHERE id = ‘123’
  4. SELECT id, username FROM user u
  5. LEFT JOIN user_address ua ON(u.id = ua.user_id)
  6. WHERE ua.state = ‘NY’
  7. GROUP BY u.id
  8. ORDER BY u.username
  9. LIMIT 0,20

 


 

12 – 代码和数据分离

这是另外一个对于所有环境下的绝大多数编程语言都适用的原则。在Web开发中,数据通常意味着HTML输出。

当PHP许多年前第一次发布时,它最开始被看作是一个模版引擎。在巨大的HTML文件里插入一些PHP代码行是非常普通的。但是,这些年来,事情发生了改变:网站变得越来越动态化和功能化。代码已经是Web程序的一个很大的部分,将它们和HTML合并在一起并不是一个好的实践。

你可以在你的程序中应用这个原则,或者你可以使用一个第三方工具(模版引擎、框架或者CMS系统)或者依照它们的习惯。

流行的PHP框架:

流行的模版引擎:

流行的CMS系统:

  • Joomla
  • Drupal


 

13 – 模版内的交替格式

你可以选择不使用一个奇特的模版引擎,取而代之的是在模版文件里使用纯内联的PHP代码。这不是必须要违反“数据和代码分离“,只是内联代码是直接和输出相关的,并且可读。在这种情况下你可以考虑使用交替格式来控制结构。

这是一个示例:

 

[c-sharp] view plaincopy

  1. <div class=”user_controls”>
  2.     <?php if ($user = Current_User::user()): ?>
  3.         Hello, <em><?php echo $user->username; ?></em> <br/>
  4.         <?php echo anchor(‘logout’, ‘Logout’); ?>
  5.     <?php else: ?>
  6.         <?php echo anchor(‘login’,’Login’); ?> |
  7.         <?php echo anchor(‘signup’, ‘Register’); ?>
  8.     <?php endif; ?>
  9. </div>
  10. <h1>My Message Board</h1>
  11. <?php foreach($categories as $category): ?>
  12.     <div class=”category”>
  13.         <h2><?php echo $category->title; ?></h2>
  14.         <?php foreach($category->Forums as $forum): ?>
  15.             <div class=”forum”>
  16.                 <h3>
  17.                     <?php echo anchor(‘forums/’.$forum->id, $forum->title) ?>
  18.                     (<?php echo $forum->Threads->count(); ?> threads)
  19.                 </h3>
  20.                 <div class=”description”>
  21.                     <?php echo $forum->description; ?>
  22.                 </div>
  23.             </div>
  24.         <?php endforeach; ?>
  25.     </div>
  26. <?php endforeach; ?>

 

这让你避免了许多大括号。同时代码看起来和HTML的结构和排版相似。


 

14 – 面向对象 vs 面向程序

面向对象编程可以帮助你创建结构化代码。但是这不代表你完全排除程序化编程。事实上创建两者混合的风格是非常棒的。

描述数据,通常是数据库里的数据,必须使用对象。

 

[c-sharp] view plaincopy

  1. class User {
  2.     public $username;
  3.     public $first_name;
  4.     public $last_name;
  5.     public $email;
  6.     public function __construct() {
  7.         // …
  8.     }
  9.     public function create() {
  10.         // …
  11.     }
  12.     public function save() {
  13.         // …
  14.     }
  15.     public function delete() {
  16.         // …
  17.     }
  18. }

 

程序化方法常用于可以独立执行的特定任务。

 

[c-sharp] view plaincopy

  1. function capitalize($string) {
  2.     $ret = strtoupper($string[0]);
  3.     $ret .= strtolower(substr($string,1));
  4.     return $ret;
  5. }

 


 

15 – 阅读开源代码

开源项目是许多开发者一起构建的。这些项目必须保持高度的代码可读性,以便他们可以尽可能高效的协同工作。

因此,通读这些项目的源代码来观察这些开发者是如何工作的是非常棒的方法。

 


16 – 代码重构

当你“重构“,你在不改变功能的情况下调整代码。你可以把它看作是“清理”,为了改进代码质量和可读性。

这并不包括bug的修复或者添加新功能。你可以重构你之前编写的代码,当它们在你头脑你还保持新鲜的时候,以便于你两个月以后有可能回顾代码时更加可读和可重用。就像那句格言所说的一样:“尽早重构,经常重构“。

你可以在重构期间应用以上任何关于代码可读性的“最佳实践“。我希望你喜欢这篇文章!我遗忘了什么?请通过回复告知我。