提高代码可读性 [英] Improving Code Readability

问题描述

当涉及代码文档时，通常会接受该代码应该自己解释，内联代码文档（不包括公共API文档）应仅解释元代码问题，如解决方法，解释为什么选择特定的实现方式等等。

When it comes to code documentation, it is usually accepted that code should explain itself, and inline code documentation (excluding public API documentation) should only explain meta-code issues such as workarounds, explanations on why specific implementations were chosen, etc.

如何完成使代码更易于阅读和更多的解释？

How do you accomplish making your code more readable and more explaining itself?

---

编辑：除了一般性评论之外，我还在寻找具体的提示。所以如果你说短而有意义的变量名，那么也可以得到一个有用的提示（例如使用三个字的原则）。

---

in addition to general comments, I'm also looking for specific tips. So if you say "short but meaningful variable names", it would be nice to also get a helpful tip as well (e.g. "use the three-word principle").

推荐答案

查看Jeff Atwood的 Code Smells 博客文章。它几乎总结了。我会添加我的个人精神，如果涉及到可读性好的代码：

Check out Jeff Atwood's Code Smells blog post. It pretty much sums it up. I'll add my personal ethos when it comes to good readable code:

• 一致性：这适用于格式化，使用大括号，命名（变量，类，方法）和目录布局（如果你把一个源目录埋在/ css下面我使用大砍刀来的话）;


• 尺寸：如果一个功能在正常的IDE中正常的字体大小的屏幕上并不完全符合屏幕，那么您需要一个很好的理由，为什么不这样做。当然，对于更长时间的功能来说，有一些有效的例子，但是它们被极大的例子大大地夸大了。必要时进行分解以保持您的功能简单;


• 评论可疑：有一些程序员倾向于使用评论来替代可读代码或简单地评论为了评论（如 / * finished * / 在之前的评论返回true; 严重的是，有什么意义？大部分（好的）代码解释自己;


• 永远不要在项目中剪切和粘贴：将代码片段从一个项目转移到另一个项目是完全可以接受的项目是一个岛屿），但您应该永远不要在一个项目之内采取一个非平凡的代码段到项目中的其他一点。不可避免地会有一个变化，你会留下一些可怜的开发人员来查看这两个或更多个代码段试图弄清楚它们是如何（可以说更重要的是为什么）;而


• 避免重复代码，如果你发现自己写同样的语句序列（或非常相似）一遍又一遍地抽象或参数化。如果你看到非常相似的语句，那么倾向于忽略它们，假设它们都是一样的（通常它们不会在某种方面很重要）。

• Consistency: this applies to formatting, using braces, naming (variables, classes, methods) and directory layout (if you bury a source directory somewhere under /css I'm coming after you with a machete);
• Size: if a function doesn't fit in its entirety on the screen in a normal IDE at a normal font size then you need a pretty darn good reason as to why not. Of course there are some valid cases for much longer functions but they are greatly outweighed by the egregious examples. Decompose as necessary to keep your functions simple;
• Comment Judiciously: there is a tendency for some programmers to use comments as a substitute for readable code or to simply comment for the sake of commenting (like /* finished */ comments right before return true;. Seriously, what's the point? Most (good) code explains itself;
• Never Cut and Paste Within a Project: it's perfectly acceptable to take a code snippet from one project to another (every project is an island) but you should never take a non-trivial code segment from within one project to some other point within the project. Inevitably one changes and you leave some poor developer with the task of looking at these two or more code segments trying to work out how (and arguably more importantly, why) they are different; and
• Avoid Repetitive Code: if you find yourself writing the same sequence of statements (or very similar) over and over again, abstract or parameterize it. If you see very similar statements the tendency is to skim over them assuming they're all the same (when typically they won't be in a way that matters).

这篇关于提高代码可读性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！