提高代码可读性

Question

在代码文档方面,通常认为代码应该自行解释,内联代码文档(不包括公共API文档)应该只解释元代码问题,例如变通方法,为什么选择特定实现的解释等等.

如何使您的代码更具可读性并更多地解释自己？

编辑: 除了一般评论,我也在寻找具体的提示.因此,如果您说"简短但有意义的变量名称",那么也可以获得有用的提示(例如"使用三字原则").

Answer 1

查看Jeff Atwood的Code Smells博客文章.它几乎总结了它.当谈到良好的可读代码时,我将添加我的个人精神:

一致性:这适用于格式化,使用大括号,命名(变量,类,方法)和目录布局(如果你将某个源目录埋在/ css下面的某个地方,我会用一把砍刀来跟踪你);
大小:如果一个函数不能完全适合普通IDE中的正常字体大小的屏幕,那么你需要一个非常好的理由,为什么不这样做.当然,有一些有效案例可以用于更长时间的功能,但是它们被极其严重的例子大大超过了它们.根据需要进行分解,以保持您的功能简单;
评论明智地说:一些程序员倾向于使用注释作为可读代码的替代,或者只是为了评论而评论(就像/* finished */之前的评论一样return true;.严重的是,重点是什么？大多数(好的)代码解释自己;
千万不要剪切和粘贴在一个项目:它是完全可以接受的花费一段代码从一个项目到另一个(每一个项目是一个岛),但你应该永远不会采取一个不平凡的代码段从一个项目中的其他一些点在项目内.不可避免地有一个变化,你让一些可怜的开发人员负责查看这两个或更多代码段,试图弄清楚他们是如何(并且可以说更重要的是,为什么)不同; 和
避免重复代码:如果你发现自己一遍又一遍地编写相同的语句序列(或非常相似),则抽象或参数化它.如果你看到非常类似的陈述,那么倾向于略过它们,假设它们都是相同的(通常它们不会以某种方式重要).

Answer 2

一致的格式化风格
善用白色空间
使用简短而有意义的名字
没有太多评论(正如你所提到的),但当我这样做时,请评论代码的原因,如果适用,请注意为什么不是(为什么不使用其他实现,特别是如果它看起来应该是显而易见的所以).
在探查器告诉我它缓慢或低效之前,不要优化代码

Answer 3

使用好的变量和方法名称.将代码分解为有意义的部分,以实现特定目的.让你的类具有凝聚力(它们一起工作)和解耦(类之间几乎没有依赖关系).不要重复自己(干).遵循鲍勃叔叔的SOLID原则(不是法律,正如他指出的那样),以达到他们努力使代码更好的程度.

Answer 4

来自'uncle bob'的书干净代码通过实际操作示例为您提供了关于函数应该如何的完整概述.

一些要点:

这本书有很多小规则,我真的推荐它.也获得Code Complete 2.