提高代码可读性的10个技巧

资讯频道 → 研发管理

0顶
0踩

2017-10-20 09:45 by 副主编 jihong10102006 评论(0) 有7091人浏览

代码可读性

声明：ITeye资讯文章的版权属于ITeye网站所有，严禁任何网站转载本文，否则必将追究法律责任！

引用

原文：10 Tips for Improving the Readability of Your Code
作者：Manas Sadangi
译者：Teixeira10

【译者注】在本文中，作者从注释，缩进，代码分组，命名方式等方面，介绍了10个提高代码可读性的技巧，供读者学习和借鉴。
以下为译文：

如果你的代码很容易阅读，这也会帮助你调试自己的程序，让工作变得更容易。

代码可读性是计算机编程领域的一个普遍课题，这也是作为开发人员首先要学习的东西。本文将详细介绍几个编写可读代码的最佳实践。

1 注释和文档

IDE(集成开发环境)在过去的几年里取得了很大的提升，也让你的代码比以前更容易进行注释了。注释会遵循一定的标准，这就允许IDE和其他工具以不同的方式来使用它们。
考虑一下这个例子:

在函数定义中添加的注释可以在使用该函数时进行查看，即使是在其他文件中使用该函数也同样可以查看注释。

下面是另一个例子，从第三方库调用函数:

在这些示例中，使用的注释(或文档)的类型基于PHPDoc，而IDE则是基于Aptana。

2 一致的缩进

你可能已经知道需要对代码进行缩进，然而，同样值得注意的是，保持缩进样式一致也是很重要的。
缩进方式不止一种，下面是两个比较常见的例子。

方式1:

function foo() {
    if($maybe){
        do_it_now();
        again();
    } else{
        abort_mission();
    }
    finalize();
}

方式2:

function foo(){  
if($maybe) {  
 do_it_now();
        again();
    }else{  
 abort_mission();
    }
    finalize();
}

我曾经使用方式2来编写代码，但最近切换到方式1。这只是一个偏好的问题，没有一种风格是“最好”的，不需要每个人都来遵循。实际上，最好的风格是一致的风格。如果你是团队的成员，或者你正在为一个项目编写代码，那么你应该遵循该项目中正在使用的样式。

当然，缩进样式并不总是完全不同，有时，它们也会混合不同的规则。例如，在PEAR编码标准中，大括号“{”会与控制结构保持一致；但是，它们也会被放在函数定义后的下一行。

PEAR Style

function foo()
{ //placed on the next line
    if($maybe) { // placed on the same line
        do_it_now();
        again();
    } else {
       abort_mission();
    }
    finalize();
}

另外，请注意，这里使用的是四个空格，而不是使用tab键进行缩进。

这是一篇维基百科的文章，有不同缩进风格的样式。

3 避免冗余的注释

对你的代码进行注释是很棒的行为，然而，它可能是过量的，或者是冗余的。来看这个例子:

// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
// if country code is US
if ($country_code == 'US'){
// display the form input for state
echo form_input_state();
}

当内容很显而易见的时候，进行重复的注释是很没有效率的。

如果你必须对该代码进行注释，那你可以简单地将其合并到一行中:

// display state selection for US users
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US'){
echo form_input_state();
}

4 代码分组

通常情况下，某些任务需要几行代码，那么把这些任务放在单独的代码块中是一个好主意，这会让它们之间有一些空间。

这里有一个简化的例子:

// get list of forums
$forums = array();
$r = mysql_query("SELECT id, name, description FROM forums");
while ($d = mysql_fetch_assoc($r)){
$forums[] = $d;
}
// load the templates
load_template('header');
load_template('forum_list', $forums);
load_template('footer');

在每个代码块的开头添加注释，视觉上看起来就是分离的代码块了。

5 一致的命名方案

PHP有时会犯不遵循一致命名方案的错误：

strpos() vs. str_split()
imagetypes() vs. image_type_to_extension()

首先，命名应该有单词边界。有两种比较流行的选择:

引用

camelCase(骆驼拼写法)：除了第一个单词,每个单词的第一个字母都大写。
underscores(下划线)：在单词之间加下划线，例如:mysql_real_escape_string()。

类似于前面提到的缩进方式，命名方式也会有不同的选择。如果现有的项目遵循一定的方案，那么你应该使用它。此外，一些语言倾向于使用一种命名方案。例如，在Java中，大多数代码都使用camelCase方式来命名，而在PHP中，大部分代码都使用underscores命名方式。

当然这些方式也可以混合，一些开发人员倾向于使用underscores方式来处理过程函数和类名，但却使用camelCase方式来对类方法命名:

classFoo_Bar{
publicfunctionsomeDummyMethod(){
}

因此，没有所谓的“最佳”风格，仅仅是需要一致的风格。

6 DRY Principle（干燥原理）

DRY意思是不要重复，即DIE: Duplication is Evil.（复制是邪恶的）
原则如下:
“每一条知识都必须在一个系统中有一个单一的、明确的、权威的表示。”

大多数应用程序(或一般计算机)的目的是使重复的任务自动化，所以这项原则应该在所有代码中体现出来，甚至是web应用程序。同样的代码不应该一次又一次地重复。

例如，大多数web应用程序由许多页面组成，很有可能这些页面包含公共元素，就比如页眉和页脚。然而，将这些页眉和页脚粘贴到每个页面并不是一个好方法。下面是Jeffrey Way解释如何在CodeIgniter中创建模板。

$this->load->view('includes/header');   
$this->load->view($main_content);   
$this->load->view('includes/footer');

7 避免嵌套太深

嵌套过多会使代码更难读取和跟踪。

functiondo_stuff(){
// ...
if (is_writable($folder)){
    if ($fp = fopen($file_path, 'w')){
        if ($stuff = get_some_stuff()){
            if (fwrite($fp, $stuff)){
// ...
   }
      else
   {
    returnfalse;
   }
  }
  else
{

为了便于阅读，通常可以修改代码以减少嵌套级别:

functiondo_stuff(){
// ...
if (!is_writable($folder)){
returnfalse;
}
if (!$fp = fopen($file_path, 'w')){
returnfalse;
}
if (!$stuff = get_some_stuff()){
returnfalse;
}
if (fwrite($fp, $stuff)){
// ...
}
  else
{
returnfalse;
}
}

8 限制行的长度

眼睛在阅读高而窄的文本时会更舒服，这正是报纸文章看起来是这样的原因:

避免编写太长的代码行是一个很好的做法。

//bad
$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();   
// good
$my_email   
->set_from('test@email.com')    
  ->add_to('programming@gmail.com')    
  ->set_subject('Methods Chained')   
  ->set_body('Some long message')   
  ->send();   
// bad
$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'";   
// good
$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'";

而且，如果有人打算从终端窗口读取代码，比如Vim用户，那么将行长度限制为大约80个字符是一个比较好的做法。

9 文件和文件夹结构
从技术上讲，可以在一个文件中编写整个应用程序的代码，但这一定是阅读和维护代码的噩梦。

在我的第一个编程项目中，我有创建“include files”的想法，然而还没有完全构建起来。我创建了一个“inc”文件夹，其中有两个文件db.php和functions.php。但随着应用程序的增加，函数文件也变得非常庞大，越来越不可维护。

最好的方法之一是使用框架或模仿文件夹结构。这就是CodeIgniter的样子:

10 一致的临时命名

通常，变量应该是描述性的，并且包含一个或多个单词。但是，这并不一定适用于临时变量，它们可以像一个字符一样短。

对于相同类型的临时变量，使用一致的命名是很好的做法。下面是我在代码中使用的一些例子:

// $i for loop countersfor
($i= 0; $i

查看图片附件

分享到：

0
顶

0
踩

评论共 0 条请登录后发表评论

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

提高代码可读性的十大注释技巧分享

主要介绍了提高代码可读性的十大注释技巧,详细分析了编程开发中常用的代码注释方法,需要的朋友可以参考下

提高代码可读性的10个注释技巧

提高代码可读性的10个注释技巧,sunshine1028,即日启程，李鸿明

提高 Python 代码可读性的 5 个基本技巧

不知道小伙伴们是否有这样的困惑，当我们回顾自己 6 个月前编写的一些代码时，往往会看的一头雾水，或者是否当我们接手其他人的代码时， Python 中有许多方法可以帮助我们理解代码的内部工作原理，良好的编程习惯，...

提高代码可读性的 8 个技巧

那些能直接看出含义的代码不需要写注释，特别是不需要为每个方法都加上注释，比如那些简单的 getter 和 setter 方法，为这些方法写注释反而让代码可读性更差。不能因为有注释就随便起个名字，而是争取起个好名字而...

提高代码可读性的注释技巧实用型

下面分享十个加注释的技巧：为每个代码块添加注释，并在每一层使用统一的注释方法和风格。例如： · 针对每个类：包括摘要信息、作者信息、以及最近修改日期等; · 针对每个方法：包括用途、功能、参...

提升代码可读性技巧

逻辑或|| 的短路运算：若左边能转成true，返回左边式子的值，反之返回右边式子的值。这里值一层的三元运算符，如果多层嵌套的三元运算符，代码可读性也很差。的短路运算有时候可以用来代替一些比较简单的if/else。

代码审查：提高代码质量的10个技巧

代码审查可以有效地改善代码质量，保障代码质量，并且减少代码缺陷和代码安全性隐患，促进团队合作，增强软件产品的稳定性和可靠性。作为开发人员，在提交代码前应该经过代码审查。然而，在实际工作中，代码

提高代码可读性的 10 个技巧

在本文中，作者从注释，缩进，代码分组，命名方式等方面，介绍了10个提高代码可读性的技巧，供读者学习和借鉴。以下为译文：如果你的代码很容易阅读，这也会帮助你调试自己的程序，让工作变得更容易。 ...

Matlab注释：提高代码可读性的小技巧

以上是几个简单的技巧，可帮助你更好地注释 Matlab 代码，提高其可读性和可理解性。为了解决这个问题，本文将介绍一些简单的技巧，帮助你更好地注释 Matlab 代码，提高其可读性和可理解性。% 这个函数计算两个数的和...

提高php代码可读性的三个技巧【转】

() ; } ...// 上百行代码... ...2.用foreach:endforeach,for:endfor,if:endif,这样的语法来写模板里的代码 ...可读性不好的写法: echo " &lt;table size= \" 100 \" &a

提升代码可读性的 10 个技巧

代码可读性是计算机编程领域中普遍存在的问题。这也是我们成为开发者首先要学习的事情之一。本文会详细介绍在编写强可读性代码时最佳实践中最重要的一部分内容。 1 - 注释和文档 IDE（Integrated ...

提高代码可读性的十大注释技巧

下面分享十个加注释的技巧： 1. 逐层注释为每个代码块添加注释，并在每一层使用统一的注释方法和风格。例如：针对每个类：包括摘要信息、作者信息、以及最近修改日期等；针对每个方法：包

DeepSeek与AI幻觉-清华大学团队制作

DeepSeek与AI幻觉-清华大学团队制作一、什么是AI幻觉（定义与基础概念）二、DeepSeek为什么会产生幻觉（聚焦特定AI模型的幻觉成因分析）三、AI幻觉评测（评估AI幻觉的频率、类型与影响的方法）四、如何减缓AI幻觉（解决方案与技术优化方向）五、AI幻觉的创造力价值（探讨幻觉在创新场景中的潜在益处，如艺术生成、灵感激发等）

协同过滤算法商品推荐系统(源码+数据库+论文+ppt)java开发springboot框架javaweb，可做计算机毕业设计或课程设计【功能需求】前台用户可以实现注册登录、商品浏览，在线客服，加入购物车，加入收藏，下单购买，个人信息管理，收货信息管理，收藏管理，评论功能。后台管理员可以进行用户管理、商品分类管理、商品信息管理、订单评价管理、系统管理、订单管理。【环境需要】 1.运行环境：最好是java jdk 1.8，我们在这个平台上运行的。其他版本理论上也可以。 2.IDE环境：IDEA，Eclipse,Myeclipse都可以。 3.tomcat环境：Tomcat 7.x,8.x,9.x版本均可 4.数据库：MySql 5.7/8.0等版本均可；【购买须知】本源码项目经过严格的调试，项目已确保无误，可直接用于课程实训或毕业设计提交。里面都有配套的运行环境软件，讲解视频，部署视频教程，一应俱全，可以自己按照教程导入运行。附有论文参考，使学习者能够快速掌握系统设计和实现的核心技术。

MES系统数字化工厂解决方案.pptx

MUI调用照片以及裁剪和图库照片上传到服务器

ChatGPT付费创作系统V3.1.3独立版 WEB端+H5端+小程序端（新增DeepSeek高级通道+新的推理输出格式）

GPT付费体验系统最新版系统是一款基于ThinkPHP框架开发的AI问答小程序，是基于国外很火的ChatGPT进行开发的Ai智能问答小程序。这是一种基于人工智能技术的问答系统，可以实现智能回答用户提出的问题。相比传统的问答系统，ChatGPT可以更加准确地理解用户的意图，提供更加精准的答案。同时系统采用了最新的GPT3.5接口与GPT4模型，同时还支持型，文心一言，腾讯混元，讯飞星火，通义千问，DeepSeeK，智普等等国内各种大模型，可以更好地适应不同的应用场景，支持站点无限多开，可以说ChatGPT付费创作系统目前国内相对体验比较好的一款的ChatGPT及多接口软件系统。新增接入DeepSeek-R1、DeepSeek-V3（Ollama自部署和第三方均支持）、高级通道增加DeepSeek、支持AI接口输出的reasoning_content字段（新的推理输出格式）、更新模型库、修复导出Excel的bug等功能，优化了云灵Midjourney接口，出图更快更稳定。小程序端变化不大该系统版本测试下来比较完美，老版本升级时数据库结构同步下，同时把原来

基于java的美食点餐管理平台设计的详细项目实例（含完整的程序，GUI设计和代码详解）

内容概要：本文档详细介绍了一款基于Java技术的美食点餐管理平台的设计与实现。该平台旨在优化传统餐饮行业的服务流程，通过智能化的点餐系统、高效的订单处理、智能库存管理和数据分析等功能，为用户提供便捷高效的点餐体验，并提升餐厅管理效率和服务质量。系统涵盖了前端设计、后端开发、数据库设计等方面，采用了成熟的Java技术和现代Web开发框架，如Spring Boot、Vue.js或React，确保系统的高效性和稳定性。此外，文档还包括详细的用户界面设计、模块实现以及系统部署指南，帮助开发者理解和搭建该平台。适合人群：具备一定的Java编程基础和技术经验的研发人员、IT从业者以及有意开发类似系统的企业和个人。使用场景及目标：①为餐厅提供一个集点餐、订单处理、库存管理于一体的高效平台；②优化传统餐饮服务流程，提升客户服务体验；③利用大数据分析辅助决策，助力餐饮企业精细化运营；④通过集成多种支付方式和其他外部系统，满足多样化的商业需求。其他说明：本项目不仅提供了完整的技术方案和支持文档，还针对实际应用场景提出了多个扩展方向和技术优化思路，旨在引导用户不断迭代和完善该平台的功能和性能。

相场模拟与激光制造技术：选择性激光烧结、激光融覆中的凝固与枝晶生长研究,相场模拟与激光制造技术：选择性激光烧结、激光融覆及凝固过程中的枝晶生长研究,相场模拟选择性激光烧结激光融覆凝固枝晶生长

相场模拟与激光制造技术：选择性激光烧结、激光融覆中的凝固与枝晶生长研究,相场模拟与激光制造技术：选择性激光烧结、激光融覆及凝固过程中的枝晶生长研究,相场模拟选择性激光烧结激光融覆凝固枝晶生长 ,相场模拟; 选择性激光烧结; 激光融覆; 凝固; 枝晶生长,相场模拟与激光工艺：枝晶生长的凝固过程研究

0顶0踩