一个偶然机会自己参加一个面试，问到什么是优秀代码？针对这个问题我的回答给出两条：可读性和可继承性。不知道当时面试官是怎么考虑我的回答的，可能对我的回答嗤之以鼻，工作十年之久连什么是优秀代码都不知道。自己回来之后反复琢磨和查找网上资料。我琢磨后给出的答案还是1. 可读性；2可继承性；3高内聚低耦合。但是通过我反复查找资料可以总结如下，优秀代码需要具备如下特征：
 
 
 
1. 满足基本需求。再优秀的代码也是为项目服务的，首先就是满足需求，针对需求编写符合需求的代码，满足功能、性能、时间等客户需求，这样才能称得上是合格代码。
 
2. 易读性。遵循命名规范，针对变量、函数、类等友好易懂的命名规则。
 
代码命名规范：
 
1)、 package包名全部由小写的ASCII字母组成，用“.”分隔。在此项目中，所有的包均以“com.abc.ticket”开头。
 
2)、 class 类名应当是名词，每个内部单词的头一个字母大写。应当使你的类名简单和具有说明性。用完整的英语单词或约定俗成的简写命名类名。
 【示例】public class UserManager
 
3)、 interface接口名应当是名词，每个内部单词的头一个字母大写。应当使你的接口名简单和具有说明性。用完整的英语单词或约定俗成的简写命名接口名。
 【示例】interface TicketManagement
 
4)、 Class 成员属性及变量的命名 (*) 变量名全部由字母组成，头一个字母小写，以后每个内部单词的头一个字母大写。变量名应该短而有意义。变量名的选择应该易于记忆。一个字符的变量名应避免，除非用于临时变量。通常临时变量名的命名规则为：i，j，k，m，n用于整数；c，d，e用于字符。
 
5)、常量的命名，Java 里的常量，是用static final 修饰的，应该用全大写加下划线命名，并且尽量指出完整含义。
 【示例】static final String SMTH_BBS="bbs.tsinghua.edu.cn";
 
6)、数组的命名，数组应该总是用下面的形式来命名：byte[] buffer;
 
7)、方法的参数和变量的命名规范一致，且应使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字。
 【示例】setCounter(int size){ this.size = size; }
 
8)、 方法命名(*)方法的命名应当使用动词，头一个字母小写，以后每个内部单词的头一个字母大写。在方法名的选择上应意义明确便于记忆。对于属性的存取方法，应使用getXXX()和setXXX()名称，以isXXX()，hasXXX()来命名返回值为boolean 类型的方法。
 
以上几条如果符合就算是好代码了吗？当然不是，这只是代码中最基本的命名规范而已，就算不符合最多就是代码不好看，没什么其他影响。
 
 
 
代码逻辑规范
 
 
1)、需求、设计中的重点功能（结合需求/设计的评审产出）
 
2)、代码格式校验
 action/façade等系统入口是否有数据格式校验
 需要存入数据库的数据字段是否有长度校验
 
3)、分支/循环
 if-else/switch是否处理了所有分支
 分支的条件语句是否有“副作用”；即，条件语句是否会改变系统状态/数据等
 循环边界是否覆盖了所有元素
 是否有死循环等
 
4）、异常处理
 是否有“吃掉异常”的情况
 是否记录了异常日志
 如果二次抛出，是否有合理的异常层次/结构
 如果内部处理，对异常的处理是否能保证后续代码正常运行
 
5）、单元测试
 是否有单元测试
 单元测试是否自动化
 单元测试是否能完整覆盖需求
 
6）、 事务处理
 事务范围是否合理；或者说，是否把不必要的操作放到了同一个事务中
 事务传播方式是否合理（required，never，new等配置）
 
7）、sql语句
 sql语句是否正确
 使用mybatis的动态语句时，是否有潜在的sql语法问题
 
8）、第三方组件
 使用Redis，RabbitMQ等组件，是否真的对组件完全了解，在使用的过程中是否正确执行了开启与关闭操作。
 
3. 可继承性。代码重用性，根据新的功能不用修改目前代码或是很少修改吧所需要的功能添加上去。
 
4. 可测性、可配置性和已修复bug。把所设计的代码根据功能进行，尽量少的bug。项目模块化，根据模块的配置进行项目的组装，成为新的项目。
 
 
 
    关于其他方面的说明定义：
 
    'Good code' is code that works, is bug free, and is readable and maintainable. Some organizations have coding 'standards' that all developers are supposed to adhere to, but everyone has different ideas about what's best, or what is too many or too few rules. There are also various theories and metrics, such as McCabe Complexity metrics. It should be kept in mind that excessive use of standards and rules can stifle productivity and creativity. 'Peer reviews', 'buddy checks' code analysis tools, etc. can be used to check for problems and enforce standards.
 
    另外，来自 MSDN END BRACKET 栏目的作者 Paul DiLascia ，也列出了优秀代码应有的物质：不管你用什么语言进行开发，所有的优秀代码都会展示出共有的经典品质：简练，易于理解，模块化，层次性，设计良好，高效，优雅，并且清晰。

作为程序员，写代码是需要一种崇高无上的精神来支撑的，写出优秀的代码，更需要你有深厚的底蕴和良好的编码习惯。在介绍写优秀代码的10个技巧之前，我们先来探讨一下什么样的代码才是优秀的代码。
 
 
 

稳定可靠（Robustness）
 
可维护且简洁（Maintainable and Simple Code）
 
高效（Fast）
 
简短（Small）
 
共享性（Reusable）
 
可测试性（Testable）
 
可移植性（Portable）
 
面对以上的目标，我们总结了以下10个写代码的技巧，希望对你有所帮助。
 
 
 

1、百家之长归我所有
 
 
 

其实写代码的方式有很多，每个人都有自己的风格，但是众多的风格中总有一些共性的、基本的写代码的风格，如为程序写注释、代码对齐，等等。是不是编程规范？对就是编程规范。
 
 
 

2、取个好名字
 
 
 

取个好的函数名、变量名，最好按照一定的规则起名。还是编程规范。
 
 
 

3、凌波微步，未必摔跤
 
 
 

这里我用“凌波微步”来形容goto语句。通常，goto语句使程序跳来跳去，不容易读，而且不能优化，但是在某种情况下，goto语句反而可以增强程序的可读性。Just go ahead，not go back。
 
 
 

4、先发制人，后发制于人
 
 
 

Defensive Coding指一些可能会出错的情况，如变量的初始化等，要考虑到出现错误情况下的处理策略。测试时要多运行几个线程。有些程序在一个线城下运行是正常的，但是在多个线程并行运行时就会出现问题；而有些程序在一个CPU运行几个线程是正常的，但是在多个CPU下运行时就会出现问题，因为单CPU运行线程只是狭义的并行，多CPU一起运行程序，才是真正的并行运算。
 
 
 

5、见招拆招，滴水不漏
 
 
 

这里的Error Case（错误情况），是指那些不易重视的错误。如果不对Error Case进行处理，程序在多数情况下不会出错，但是一旦出现异常，程序就会崩溃。
 
 
 

6、熟习剑法刀术，所向无敌
 
 
 

用“剑法刀术”来形容一些API是因为它们都是经过了很多优秀开发人员的不断开发、测试，其效率很高，而且简洁易懂，希望大家能掌握它，熟悉它，使用它。是不是象我们的ULIB。
 
 
 

7、双手互搏，无坚不摧
 
 
 

这里的测试不是指别人来测试你的代码，而是指自己去测试。因为你是写代码的原作者，对代码的了解最深，别人不可能比你更了解，所以你自己在测试时，可以很好地去测试哪些边界条件，以及一些意向不到的情况。
 
 
 

8、活用断言
 
 
 

断言（assertion）是个很好的调试工具和方法，希望大家能多用断言，但是并不是所有的情况下都可以用到断言。有些情况使用断言反而不合适。
 
 
 

9、草木皆兵，不可大意
 
 
 

是指在写代码时，要小心一些输入的情况，比如输入文件、TCP的sockets、函数的参数等等，不要认为使用我们的API的用户都知道什么是正确的、什么是错的，也就是说一定要考虑到对外接口的出错处理问题。
 
 
 

10、最高境界，无招胜有招
 
 
 

意思就是说尽量避免写太多的代码，写的越多，出错的机会也越多。最好能重用别人开放的接口函数或直接调用别人的api。

 别以为你可以理解自己写的代码，过了两个星期之后，你可能就不知道代码是不是自己写的。
 
 如果是简单的代码，不加注释情有可原，但是，复杂的代码那就必须加注释了。
 
 
 
 
 1、代码注释最基本的原则
 
 　　代码注释一定是注明代码的目的，而不是代码的行为。为何呢?因为通过代码我们就可以清楚行为，多加注释，画蛇添足。
 
 2、使用空格对齐注释行
 
 　　为了方便阅读起见，代码注释对齐会更好一些。那么问题来了，是用tab对齐还是用空格键对齐呢?
 
 　　我们都清楚，tab在不同的编辑器和集成开发环境中是不一样的，所以选择空格键对齐会适合一些。
 
 　　const MAX_ITEMS = 10; // maximum number of packets
 
 　　const MASK = 0x1F; // mask bit TCP
 
 3、代码少而精
 
 　　如果说代码注释一定要有，那就就要尽量做到少而精。有些人代码注释写的跟小说一样，这后果是相当严重的...
 
 4、代码“统帅”段落
 
 　　一些程序员习惯将代码分成多个“段落”，这是非常要好的一个习惯。当然，加个代码注释就会锦上添花。比如在段落代码前加个注释。同样地，就是告诉自己或者维护人员代码的意图。
 
 5、代码注释的精髓
 

 

  


  
 本系列文章由@浅墨_毛星云 出品，转载请注明出处。  
 文章链接： http://blog.csdn.net/poem_qianmo/article/details/52268975
 作者：毛星云（浅墨）    微博：http://weibo.com/u/1723155442 
  

  


  


  

这篇文章将与大家一起聊一聊，书写代码过程中一些良好的格式规范。

  


  


  


 
 
一、引言
 


 


 
以下引言的内容，有必要伴随这个系列的每一次更新，这次也不例外。
 
 
 
《代码整洁之道》这本书提出了一个观点：代码质量与其整洁度成正比，干净的代码，既在质量上可靠，也为后期维护、升级奠定了良好基础。书中介绍的规则均来自作者多年的实践经验，涵盖从命名到重构的多个编程方面，虽为一“家”之言，然诚有可资借鉴的价值。
 
 
 
但我们知道，很多时候，理想很丰满，现实很骨感，也知道人在江湖，身不由己。因为项目的紧迫性，需求的多样性，我们无法时时刻刻都写出整洁的代码，保持自己输出的都是高质量、优雅的代码。
 
 
 
但若我们理解了代码整洁之道的精髓，我们会知道怎样让自己的代码更加优雅、整洁、易读、易扩展，知道真正整洁的代码应该是怎么样的，也许就会渐渐养成持续输出整洁代码的习惯。
 
 
 
而且或许你会发现，若你一直保持输出整洁代码的习惯，长期来看，会让你的整体效率和代码质量大大提升。
 
 
 


 


 
 
 

 
二、本文涉及知识点思维导图
 

 


 


 


 
国际惯例，先放出这篇文章所涉及内容知识点的一张思维导图，就开始正文。大家若是疲于阅读文章正文，直接看这张图，也是可以Get到本文的主要知识点的大概。
 


 


 


 


 


 


 


 
三、优秀代码的书写格式准则
 
 
 


 


 

  
1 像报纸一样一目了然
 
 


 
想想那些阅读量巨大的报纸文章。你从上到下阅读。在顶部，你希望有个头条，告诉你故事主题，好让你决定是否要读下去。第一段是整个故事的大纲，给出粗线条概述，但隐藏了故事细节。接着读下去，细节渐次增加，直至你了解所有的日期、名字、引语、说话及其他细节。
 
 
 
优秀的源文件也要像报纸文章一样。名称应当简单并且一目了然，名称本身应该足够告诉我们是否在正确的模块中。源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。
 
 
 


 
 
 

  
2 恰如其分的注释
 
 


 
带有少量注释的整洁而有力的代码，比带有大量注释的零碎而复杂的代码更加优秀。
 
我们知道，注释是为代码服务的，注释的存在大多数原因是为了代码更加易读，但注释并不能美化糟糕的代码。
 
 
 
另外，注意一点。注释存在的时间越久，就会离其所描述的代码的意义越远，越来越变得全然错误，因为大多数程序员们不能坚持（或者因为忘了）去维护注释。
 


 
当然，教学性质的代码，多半是注释越详细越好。
 
 
 


 


 

  
3 合适的单文件行数
 
 
 
 
尽可能用几百行以内的单文件来构造出出色的系统，因为短文件通常比长文件更易于理解。当然，和之前的一些准则一样，只是提供大方向，并非不可违背。
 


 
例如，《代码整洁之道》第五章中提到的FitNess系统，就是由大多数为200行、最长500行的单个文件来构造出总长约5万行的出色系统。
 


 
 
 
 
 

  
4 合理地利用空白行
 
 


 
古诗中有留白，代码的书写中也要有适当的留白，也就是空白行。
 
在每个命名空间、类、函数之间，都需用空白行隔开（应该大家在学编程之初，就早有遵守）。这条极其简单的规则极大地影响到了代码的视觉外观。每个空白行都是一条线索，标识出新的独立概念。
 
其实，在往下读代码时，你会发现你的目光总停留于空白行之后的那一行。用空白行隔开每个命名空间、类、函数，代码的可读性会大大提升。
 


 
 
 


 

  
5 让紧密相关的代码相互靠近
 
 


 
如果说空白行隔开了概念，那么靠近的代码行则暗示了他们之间的紧密联系。所以，紧密相关的代码应该相互靠近。
 
 
 
举个反例（代码段1）：
 

 
public class ReporterConfig
{
    /**
    * The class name of the reporter listener
    */
    private String m_className;

    /**
    * The properties of the reporter listener
    */
    private List<Property> m_properties = new ArrayList<Property>();

    public void addProperty(Property property)
    {
        m_properties.add(property);
    }
}
 

 
再看个正面示例（代码段2）：
 

 
public class ReporterConfig
{
    private String m_className;
    private List<Property> m_properties = new ArrayList<Property>();

    public void addProperty(Property property)
    {
        m_properties.add(property);
    }
}
 

 
以上这段正面示例（代码段2）比反例（代码段1）中的代码好太多，它正好一览无遗，一眼就能看这个是有两个变量和一个方法的类。而再看看反例，注释简直画蛇添足，隔断了两个实体变量间的联系，我们不得不移动头部和眼球，才能获得相同的理解度。
 


 


 


 


 

  
6 基于关联的代码分布
 
 


 
关系密切的概念应该相互靠近。对于那些关系密切、放置于同一源文件中的概念，他们之间的区隔应该成为对相互的易懂度有多重要的衡量标准。应该避免迫使读者在源文件和类中跳来跳去。变量的声明应尽可能靠近其使用位置。
 
对于大多数短函数，函数中的本地变量应当在函数的顶部出现。例如如下代码中的is变量的声明：
 

 
private static void readPreferences()
{
    InputStream is= null;
    try
    {
        is= new FileInputStream(getPreferencesFile());
        setPreferences(new Properties(getPreferences()));
        getPreferences().load(is);
    }
    catch (IOException e)
    {
        DoSomeThing();
    }
}
 


 
而循环中的控制变量应该总在循环语句中声明，例如如下代码中each变量的声明：
 

 
public int countTestCases()
{
    int count = 0;
    for (Test each : tests)
        count += each.countTestCases();
    return count;
}
 
在某些较长的函数中，变量也可能在某代码块的顶部，或在循环之前声明。例如如下代码中tr变量的声明：
 

 
...
for (XmlTest test : m_suite.getTests()) 
{
    TestRunner tr = m_runnerFactory.newTestRunner(this, test);
    tr.addListener(m_textReporter);
    m_testRunners.add(tr);
    invoker = tr.getInvoker();
    for (ITestNGMethod m : tr.getBeforeSuiteMethods()) 
    {
        beforeSuiteMethods.put(m.getMethod(), m);
    }
    for (ITestNGMethod m : tr.getAfterSuiteMethods())
    {
        afterSuiteMethods.put(m.getMethod(), m);
    }
}
...
 

 

 
另外，实体变量应当在类的顶部声明（也有一些流派喜欢将实体变量放到类的底部）。
 
若某个函数调用了另一个，就应该把它们放到一起，而且调用者应该尽量放到被调用者上面。这样，程序就有自然的顺序。若坚定地遵守这条约定，读者将能够确信函数声明总会在其调用后很快出现。
 
概念相关的代码应该放到一起。相关性越强，则彼此之间的距离就该越短。
 
 
 
这一节的要点整理一下，大致就是：
 

 
变量的声明应尽可能靠近其使用位置。
循环中的控制变量应该在循环语句中声明。
短函数中的本地变量应当在函数的顶部声明。
而对于某些长函数，变量也可以在某代码块的顶部，或在循环之前声明。
实体变量应当在类的顶部声明。
若某个函数调用了另一个，就应该把它们放到一起，而且调用者应该尽量放到被调用者上面。
概念相关的代码应该放到一起。相关性越强，则彼此之间的距离就该越短。
 

 
 
 


 


 

  
7 团队遵从同一套代码规范
 
 
 
 
一个好的团队应当约定与遵从一套代码规范，并且每个成员都应当采用此风格。我们希望一个项目中的代码拥有相似甚至相同的风格，像默契无间的团队所完成的艺术品，而不是像一大票意见相左的个人所堆砌起来的残次品。
 


 
定制一套编码与格式风格不需要太多时间，但对整个团队代码风格统一性的提升，却是立竿见影的。
 


 
记住，好的软件系统是由一系列风格一致的代码文件组成的。尽量不要用各种不同的风格来构成一个项目的各个部分，这样会增加项目本身的复杂度与混乱程度。
 
 
 


 


 


 


 
四、范例代码
 
 
 


 


 
和上篇文章一样，有必要贴出一段书中推崇的整洁代码作为本次代码书写格式的范例。书中的这段代码采用java语言，但丝毫不影响使用C++和C#的朋友们阅读。
 

 
public class CodeAnalyzer implements JavaFileAnalysis
{
    private int lineCount;
    private int maxLineWidth;
    private int widestLineNumber;
    private LineWidthHistogram lineWidthHistogram;
    private int totalChars;

    public CodeAnalyzer()
    {
        lineWidthHistogram = new LineWidthHistogram();
    }

    public static List<File> findJavaFiles(File parentDirectory)
    {
        List<File> files = new ArrayList<File>();
        findJavaFiles(parentDirectory, files);
        return files;
    }

    private static void findJavaFiles(File parentDirectory, List<File> files)
    {
        for (File file : parentDirectory.listFiles())
        {
            if (file.getName().endsWith(".java"))
                files.add(file);
            else if (file.isDirectory())
                findJavaFiles(file, files);
        }
    }

    public void analyzeFile(File javaFile) throws Exception
    {
        BufferedReader br = new BufferedReader(new FileReader(javaFile));
    	String line;
    	while ((line = br.readLine()) != null)
    	measureLine(line);
    }

    private void measureLine(String line)
    {
        lineCount++;
        int lineSize = line.length();
        totalChars += lineSize;
        lineWidthHistogram.addLine(lineSize, lineCount);
        recordWidestLine(lineSize);
    }

    private void recordWidestLine(int lineSize)
    {
        if (lineSize > maxLineWidth)
        {
            maxLineWidth = lineSize;
            widestLineNumber = lineCount;
        }
    }

    public int getLineCount()
    {
        return lineCount;
    }

    public int getMaxLineWidth()
    {
        return maxLineWidth;
    }

    public int getWidestLineNumber()
    {
        return widestLineNumber;
    }

    public LineWidthHistogram getLineWidthHistogram()
    {
        return lineWidthHistogram;
    }

    public double getMeanLineWidth()
    {
        return (double)totalChars / lineCount;
    }

    public int getMedianLineWidth()
    {
        Integer[] sortedWidths = getSortedWidths();
        int cumulativeLineCount = 0;
        for (int width : sortedWidths)
        {
            cumulativeLineCount += lineCountForWidth(width);
            if (cumulativeLineCount > lineCount / 2)
                return width;
        }
        throw new Error("Cannot get here");
    }

    private int lineCountForWidth(int width)
    {
        return lineWidthHistogram.getLinesforWidth(width).size();
    }

    private Integer[] getSortedWidths()
    {
        Set<Integer> widths = lineWidthHistogram.getWidths();
        Integer[] sortedWidths = (widths.toArray(new Integer[0]));
        Arrays.sort(sortedWidths);
        return sortedWidths;
    }
}
 

 

 

 


 


 


 


 
五、小结：让代码不仅仅是能工作
 


 


 
代码的格式关乎沟通，而沟通是专业开发者的头等大事，所以良好代码的格式至关重要。
 


 
或许之前我们认为“让代码能工作”才是专业开发者的头等大事。然而，《代码整洁之道》这本书，希望我们能抛弃这个观点。
 


 
让代码能工作确实是代码存在的首要意义，但作为一名有追求的程序员，请你想一想，今天你编写的功能，极可能在下一版中被修改，但代码的可读性却会对以后可能发生的修改行为产生深远影响。原始代码修改之后很久，其代码风格和可读性仍会影响到可维护性和扩展性。即便代码已不复存在，你的风格和律条仍影响深远。
 
 
 
“当有人在阅读我们的代码时，我们希望他们能为其整洁性、一致性和优秀的细节处理而震惊。我们希望他们高高扬起眉毛，一路看下去，希望他们感受能到那些为之劳作的专业人士们的优秀职业素养。但若他们看到的只是一堆由酒醉的水手写出的鬼画符，那他们多半会得出结论——这个项目的其他部分应该也是混乱不堪的。”
 
 
 
所以，各位，在开发过程中请不要仅仅是停留在“让代码可以工作”的层面，而更要注重自身输出代码的可维护性与扩展性。请做一个更有追求的程序员。
 

 

 


 


 
 
 
六、本文涉及知识点提炼整理
 


 


 
整洁代码的书写格式，可以遵从如下几个原则：
 
 
 
第一原则：像报纸一样一目了然。优秀的源文件也要像报纸文章一样，名称应当简单并且一目了然，名称本身应该足够告诉我们是否在正确的模块中。源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。
 
第二原则：恰如其分的注释。带有少量注释的整洁而有力的代码，比带有大量注释的零碎而复杂的代码更加优秀。
 
第三原则：合适的单文件行数。尽可能用几百行以内的单文件来构造出出色的系统，因为短文件通常比长文件更易于理解。
 
第四原则：合理地利用空白行。在每个命名空间、类、函数之间，都需用空白行隔开。
 
第五原则：让紧密相关的代码相互靠近。靠近的代码行暗示着他们之间的紧密联系。所以，紧密相关的代码应该相互靠近。
 
第六原则：基于关联的代码分布。
 

 
变量的声明应尽可能靠近其使用位置。
循环中的控制变量应该在循环语句中声明。
短函数中的本地变量应当在函数的顶部声明。
对于某些长函数，变量也可以在某代码块的顶部，或在循环之前声明。
实体变量应当在类的顶部声明。
若某个函数调用了另一个，就应该把它们放到一起，而且调用者应该尽量放到被调用者上面。
概念相关的代码应该放到一起。相关性越强，则彼此之间的距离就该越短。
 

  

 
 
第七原则：团队遵从同一套代码规范。一个好的团队应当约定与遵从一套代码规范，并且每个成员都应当采用此风格。
 
 
 

 


 


 

 
本文就此结束。
 
下篇文章，我们将继续《代码整洁之道》的精读与演绎，探讨更多的内容。
 
With Best Wishes.