如何编写高质量的代码

<section id="nice" data-tool="mdnice编辑器" data-website="https://www.mdnice.com" style="line-height: 1.6; word-break: break-word; word-wrap: break-word; text-align: left; font-family: Optima-Regular, Optima, PingFangSC-light, PingFangTC-light, 'PingFang SC', Cambria, Cochin, Georgia, Times, 'Times New Roman', serif; padding: 5px; font-size: 16px; color: #353535; word-spacing: 0.8px; letter-spacing: 0.8px; border-radius: 16px;">  刚来我现在这个公司的时候，还有在腾讯去优化外包员工写的代码的时候。总会遇到一些问题，相信大家也跟我一样会遇到过这些问题： <ol data-tool="mdnice编辑器" style="margin-top: 8px; margin-bottom: 8px; padding-left: 25px; list-style-type: decimal; color: #f83929; font-size: 16px;"> <li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">接手的项目，文档缺失，代码一点注释没有，交接维护的人已经离职，所以基本上只能靠自己猜来梳理代码逻辑。</section></li><li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">代码风格过于抽象（命名缩写且意思不明确，直接用字母或者加上数字命名，比如 Student s， int num1，int num2，重名方法等），看不懂，也不敢轻易修改。</section></li><li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">运行的代码，不打印日志，info日志没有，error日志没有。sql不打印。或者分布式情况下，没有logid做全局追踪</section></li></ol> <ul data-tool="mdnice编辑器" style="margin-top: 8px; margin-bottom: 8px; padding-left: 25px; list-style-type: disc; color: #f83929; font-size: 16px;"> <li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">代码写的过于low，if else嵌套了n层，或者一个方法，写了一百多行，甚至几百行。扩展性差，重构优化费时，费力。一般不敢轻易优化</section></li></ul> <ol start="4" data-tool="mdnice编辑器" style="margin-top: 8px; margin-bottom: 8px; padding-left: 25px; list-style-type: decimal; color: #f83929; font-size: 16px;"> <li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">业务代码和逻辑代码不分家，全写一起，service层基本无作用，全再controller层做操作</section></li></ol>   我上面的一列，你有没有感触，发没发现就是你遇到过的所有的问题。其实，根本原因就是代码可读性差，没能很好的串联起代码内在的逻辑。可读性差的代码不仅代码难以理解，维护起来也是相当的头疼，最终导致交付效率变差。 今天来讲一下如何快速提高代码的可读性 <h1 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; border-top: 2px solid rgb(248, 57, 41); text-align: center; font-size: 1.3em;">为什么要提高代码的可读性</h1>    提升源代码的可读性主要有以下四大好处。    <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">第一，更易于维护。</h2>    代码写好后，需要调试、运行与修复 Bug，设计文档、需求文档和口头交流只能表达部分业务逻辑的意图，而代码则能反映出编程实现业务逻辑时的全部真实意图。可读性高的代码，能让阅读者在阅读时快速理解编写者的意图，即便逻辑复杂，也能在修改时准确地分析和理解，大大节省维护和修改代码的时间。 <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">第二，更易于重构。</h2>    现在很多项目之所以难以重构，就是因为代码的可读性太差。当你无法理解一段代码时，你会跳过它，而整个系统都难以理解的话，你可能就会选择重写而不是重构，因为重构必然会修改原有代码，这会引入一定的风险，一旦因为重构而导致故障，那么维护的人就要担责。所以说，可读性的高低在某种程度上决定了你重构意愿的大小。（这里我相信大部分人其实都碰到过入职接手别人的代码，可能因为那个人在你入职之前就离职了，也可能因为他跟你交接的时候并没有交接完整就匆匆的离职了，导致你对现有的代码并不熟悉，公司的业务发展，提了新需求要求你去改原本的代码，但是你这时候看不懂，所以你只能自己去重写一个方法，之后去调用你重写之后的接口，我相信大部分人都这么做过，我也这么做过） <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">第三，更易于测试。</h2>    代码在修改时需要反复调试，如果代码的可读性很差，那么很多时候都需要写一些额外的 Mock 或测试接口来对原有的代码进行测试，不仅浪费时间，还容易造成误读。可读性高的代码，参数与输出都更清晰，在测试时能更精准地找到对应逻辑和问题点。 <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">第四，更易于应用设计模式。</h2>    设计模式除了在设计之初被使用外，其实更多时候都是在代码重构过程中被使用。在工作中，你会发现有的代码虽然写了很多嵌套的if-else，但命名和注释都写得很好，逻辑也很易读，在重构时就能通过设计模式很好地去优化。而有的代码虽然看上去很简洁，但使用了很多高级技巧或缩写命名，理解起来非常费时、费力，对于维护人员来说，自然不愿意考虑使用设计模式。    虽说编写文档能够表达软件开发意图，但事实上，你可能很讨厌写文档，这是因为大部分文档都与代码没有直接关系，并且随着代码的不断调试与修改，文档会变得越来越难以与最新的真实情况同步。    另外，你可能也没有太多时间阅读文档，需求上线、Bug 修复、多项目并发是现在程序员的日常现状。因为时间紧、任务重，你可能只能边改代码边学习，这时一份逻辑清晰的代码才是你真正需要的。    可以换个角度想想，假如你是代码使用者，你希望看到什么样的代码？ 很明显，没有人想要看到这样的代码 <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">cName = InpList.get(0).replace(",", ".");                     cCode = InpList.get(1).replace(",", ".");                     cAlpha2 = InpList.get(2).replace(",", ".");                     cAbreviation = InpList.get(3).replace(",", ".");                     dYear = InpList.get(4).replace(",", ".");                     dPoliticalCompatibility = InpList.get(5).replace(",", ".");                     dRankPoliticalCompatibility = InpList.get(6).replace(",", ".");                     dEconomicCompatibility = InpList.get(7).replace(",", ".");                     dRankEconomicCompatibility = InpList.get(8).replace(",", ".");                     dMilitaryCompatibility = InpList.get(9).replace(",", ".");                     dRankMilitaryCompatibility = InpList.get(10).replace(",", ".");                     dDemoScore = InpList.get(11).replace(",", ".");                     dRankDemoScore = InpList.get(12).replace(",", ".");                     dEnvironmentalCompatibility = InpList.get(13).replace(",", ".");                     dRankEnvironmentalCompatibility = InpList.get(14).replace(",", ".");                     dSumCompatibility = InpList.get(15).replace(",", ".");                     dRankCompatibility = InpList.get(16).replace(",", ".");                     dPoliticalUtility = InpList.get(17).replace(",", ".");                     dRankPoliticalUtility = InpList.get(18).replace(",", ".");                     dEconomicUtility = InpList.get(19).replace(",", ".");                     dRankEconomicUtility = InpList.get(20).replace(",", ".");                     dMilitaryUtility = InpList.get(21).replace(",", ".");                     dRankMilitaryUtility = InpList.get(22).replace(",", ".");                     dEnvironmentalUtility = InpList.get(23).replace(",", ".");                     dRankEnvironmentalUtility = InpList.get(24).replace(",", ".");                     dSumUtility = InpList.get(25).replace(",", ".");                     dRankUtility = InpList.get(26).replace(",", ".");                     dPoliticalScore = InpList.get(27).replace(",", ".");                     dRankPoliticalScore = InpList.get(28).replace(",", ".");                     dEconomicScore = InpList.get(29).replace(",", ".");                     dRankEconomicScore = InpList.get(30).replace(",", ".");                     dMilitaryScore = InpList.get(31).replace(",", ".");                     dRankMilitaryScore = InpList.get(32).replace(",", ".");                     dEnvironmentalScore = InpList.get(33).replace(",", ".");                     dRankEnvironmentalScore = InpList.get(34).replace(",", ".");                     dAggregate = InpList.get(35).replace(",", ".");                     dRankAggregate = InpList.get(36).replace(",", "."); </code></pre> 而是，希望看到这样的代码（HttpClient 的某个代码片段）： <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">/**  * {@inheritDoc}  */ @Override public CloseableHttpResponse execute(         final HttpUriRequest request,         final HttpContext context) throws IOException, ClientProtocolException {     Args.notNull(request, "HTTP request");     return doExecute(determineTarget(request), request, context); } private static HttpHost determineTarget(final HttpUriRequest request) throws ClientProtocolException {     // A null target may be acceptable if there is a default target.     // Otherwise, the null target is detected in the director.     HttpHost target = null;     final URI requestURI = request.getURI();     if (requestURI.isAbsolute()) {         target = URIUtils.extractHost(requestURI);         if (target == null) {             throw new ClientProtocolException("URI does not specify a valid host name: "                     + requestURI);         }     }     return target; } </code></pre>    所以说，在开发代码时，应该更注重代码表达的意图是否清晰，考虑使用一些方法和技巧，虽然会耗费一点时间，但是从整体来看，你会节省很多沟通与解释的时间，做到在真正的提升编码效率。 <h1 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; border-top: 2px solid rgb(248, 57, 41); text-align: center; font-size: 1.3em;">如何写出有“逻辑线索”的源代码</h1>    要想写出可读性高的代码，你可以从三个方面来入手。 <ul data-tool="mdnice编辑器" style="margin-top: 8px; margin-bottom: 8px; padding-left: 25px; list-style-type: disc; color: #f83929; font-size: 16px;"> <li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">代码表现形式:在命名（变量名、方法名、类名）、代码格式、注释等方面的改进。</section></li><li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">控制流和逻辑：尽量分离控制流和逻辑，让代码变得更容易理解。</section></li><li><section style="margin-top: 5px; margin-bottom: 5px; line-height: 26px; text-align: left; font-weight: 500; color: #353535;">惯性思维：找出常犯的一些惯性思考方式并逐一改进。</section></li></ul> 下面我就来具体解释下。 <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">优化代码表现形式</h2>    命名在编程中至关重要，无论是变量名、类名还是方法名，好的名字能快速准确地传达要表达的含义，而缩写、自定义名称会让代码变得难以理解。我们先来看一段代码： <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">public class T {     private Set<String> pns = new HashSet();     private int s = 0;     private Boolean f(String n) {return pns.contains(n);}     int getS() {return s;}     int s(List<T> ts, String n) {         for (T t :ts)              if (t.f(n))                  return t.getS();         return 0;     } } </code></pre>    这段代码到底实现了什么功能？估计没有人能回答出来。如果编写者不是我，我肯定也无法理解这段代码。光凭看代码，几乎是无法理解这段代码的真实含义到底是什么的。    实际上，这个类是获取球队比赛得分的，除了通过球队直接获得比赛得分外，还可以通过球队里的某个球员来查找对应得分，具体修改如下： <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">/**  * 获取球队比赛得分  **/ public class Team {     private Set<String> playerNames = new HashSet(); //保证名字不重复     private int score = 0; //默认为零          /**      * 判断是否包含球员      * @param playerName      * @return      */     private Boolean containsPlayer(String playerName) {         return playerNames.contains(playerName);     }          /**      * 知道队伍，直接获取分数      * @return      */     public int getScore() {         return score;     }          /**      * 通过队员名字查找所属队伍分数      * @param teams 支持多个队伍      * @param playerName       * @return 兜底为0分，不出现负分      */     public int getTeamScoreForPlayer(List<Team> teams, String playerName) {         for (Team team :teams) {             if (team.containsPlayer(playerName)) {                 return team.getScore();             }         }         return 0;     } } </code></pre> 从优化后的代码中，你就能直观地看到， “命名的优化加上注释的说明”一下子就让源代码的逻辑变得清晰起来，即便你没有学过编程，也能大致了解这段代码的逻辑和作用。 <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">改进控制流和逻辑</h2> <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">public List<User> getUsers(int id) {     List<User> result = new ArrayList<>();     User user = getUserById(id);     if (null != user) {         Manager manager = user.getManager();         if (null != manager) {             List<User> users = manager.getUsers();             if (null != users && users.size() > 0) {                 for (User user1 : users) {                     if (user1.getAge() >= 35 && "MALE".equals(user1.getSex())) {                         result.add(user1);                     }                 }             } else {                 System.out.println("获取员工列表失败");             }         } else {             System.out.println("获取领导信息失败");         }     } else {         System.out.println("获取员工信息失败");     }     return result; } </code></pre>    这段代码的含义是：想要通过 id 来查询员工的信息，如果 id找不到，就查询员工的领导，然后通过他领导下的员工信息来寻找，这时还需要判断员工年龄大于 35 岁且为男性。    这是我们最常使用的逻辑实现方式，俗称 箭头型代码，但是随着判断条件逐渐增多，嵌套就会增多。代码逻辑越多，你就越容易搞不清楚逻辑是什么，因为看到最内层的代码时，你已经忘记前面每一层的条件判断是什么了。    那么，我们该如何去优化呢？其实很简单，就是改变控制流，先判断会出现失败的条件，一旦出现优先退出。优化后的代码如下： <pre class="custom" data-tool="mdnice编辑器" style="margin-top: 10px; margin-bottom: 10px; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px;"><span style="display: block; background: url(https://files.mdnice.com/user/3441/876cad08-0422-409d-bb5a-08afec5da8ee.svg); height: 30px; width: 100%; background-size: 40px; background-repeat: no-repeat; background-color: #282c34; margin-bottom: -7px; border-radius: 5px; background-position: 10px 10px;"><code class="hljs" style="overflow-x: auto; padding: 16px; color: #abb2bf; display: -webkit-box; font-family: Operator Mono, Consolas, Monaco, Menlo, monospace; font-size: 12px; -webkit-overflow-scrolling: touch; padding-top: 15px; background: #282c34; border-radius: 5px;">public List<User> getStudents(int uid) {     List<User> result = new ArrayList<>();     User user = getUserByUid(uid);     if (null == user) {         System.out.println("获取员工信息失败");         return result;     }     Manager manager = user.getManager();     if (null == manager) {         System.out.println("获取领导信息失败");         return result;     }     List<User> users = manager.getUsers();     if (null == users || users.size() == 0) {         System.out.println("获取员工列表失败");         return result;     }     for (User user1 : users) {         if (user1.getAge() > 35 && "MALE".equals(user1.getSex())) {             result.add(user1);         }     }     return result; } </code></pre>    现在，代码逻辑是不是很清晰了？虽然这个快速失败方法很简单，但是非常有效。实际上，快速失败就是 KISS 原则一个很好的实践，这样能保证条件判断的逻辑简单清晰。只要 if 的嵌套超过三层，你就可以应用这个原则来改进控制流，让逻辑更清晰易懂。 <h2 data-tool="mdnice编辑器" style="margin-top: 30px; margin-bottom: 15px; padding: 0px; font-weight: bold; color: black; font-size: 22px; text-align: left; margin: 20px 10px 0px 0px;">避免惯性思维</h2>    除了改进表层和逻辑外，我们更应该尽量避免设计代码时的一些惯性思维，这里我总结出了“五个避免”，下面我们就来具体分析一下。    第一，要避免一次性代码。 一次性编码最大的坏处在于，一旦需要修改，多处就得跟着修改，而多次修改又可能会出现遗漏的风险。一次性代码在越来越多的软件代码中出现，一个本质的原因就是多人协作开发的情况越来越多。由于编程是一件非标准化的事情，不同程序员可能对同一个逻辑的理解完全不同，而一旦每个人都只从自己的角度出发写一次性代码，那么同一个系统里的代码很快就会变得冗余与混乱。    第二，要避免复制粘贴代码。 一方面，不同的人编码风格可能会有所不同，这会给阅读者在理解上造成一定的认知负担（需要来回切换判断标准）。另一方面，还会带来未知 Bug的风险。复制过来的代码，更多是关注输入和输出，一旦代码正常运行后，很少会去关注代码的内部逻辑，但是等出现问题后，再想去梳理逻辑反而变得更加困难（因为不知道详细的实现逻辑）    第三，避免写超长代码。 超长代码带来的最大问题是：在阅读代码时，函数方法之间的跳转过多，思维很容易发生混乱，尤其对于一些命名相同但参数不同的方法，很容易出现修改错误的情况。从编写者的角度来看，你写超长代码，可能是觉得在一个文件里维护代码比较方便；但对于阅读者来说，他可能并不知道你是如何对代码进行职责划分的，更多时候他都会以为一个类里都是一个职责，但实际上一旦出现多个职责，加上逻辑跳转很多，阅读者基本上是会放弃阅读的。    第四，避免过度简化命名和表达式。 在开发任务重的时候，我们通常会选用一些简化命名的方法，比如，num1、num2、num3 这类变量命名形式。虽然在写代码的时候，我们可能记得这些变量的含义，但是过一段时间后，如果没有注释或说明，几乎是不可能直接通过名字知道它们的作用的，还得借助上下文代码，这样不仅费时，而且还可能会出现理解错误的情况。    第五，避免写“是什么”的注释。 代码的命名和结构如果能直接反映出来“是什么”的话，我们就不应该用注释去表达，因为看代码一眼就能明白，比如，获取用户信息的方法名——get 和 getFromUserInfo。我们应该多写“为什么”的注释，比如，为什么要多加一个适配的方法，原因可能是线上 xxx 问题引起，或临时修复的Bug，后续可能随 xxx 接口调整而废弃，等等。在很多优秀的开源框架中，我们都能看到作者会在 interface 接口上写很多“为什么”的说明，就是为了帮助我们快速抓住代码的逻辑线索。另外，写“为什么”的注释还有一个好处：尤其在早期快速迭代过程中，能给后来的维护者提供一个优化的切入点，而不至于交接代码后让维护代码的人看不懂、不敢动。 </section>

如何编写高质量的代码

评论区

相关推荐