资讯频道 → 研发管理
阅读更多

2顶
1踩

研发管理

翻译新闻 10 个代码注释及格式化的最佳实践

2012-03-26 16:32 by 正式编辑 sherry617 评论(7) 有7664人浏览
代码格式 注释
代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。

一、注释

注释是代码的一部分，其重要性显而易见。缺少注释的代码可以说是没有用的，虽然有人建议使用自文档化代码，不过我们认为自文档化+代码文档是最好的。

1. 只在必要时使用注释

也就是说不需要对每一行都使用注释 
int count = 0; // 将count的初始值赋为0(?!?)

但缺少注释会增加维护难度，所以变量、方法的命名应该易于理解 
int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)
List<int> getVal(int val, int len, String op) //(?!?)

2. 错误的注释还不如没有注释，应尽量避免。

3. 为重要的且没有自文档化的变量写注释。

4. 为公开的方法写注释（例如JavaDoc declaration），当然，这些注释应该是真的有必要添加的。

5. 类似“了解”、“待办”的注释也许对当天来说很重要，但之后应该删除。

二、格式化

有很多开发工具（如maven checkstyle）都提供代码格式化的功能，且格式化操作可在代码保存时自动进行，但这些格式不一定符合公司的格式规则，因此在使用之前要对其进行设置。

1. 使用一致的括号格式。括号一般都加在当前行的尾部或新一行的首部，选择一种添加方式，并在所有代码行中保持相同的格式。

2. 使用一致的空行。空行用于分隔代码和语义组，提高代码可读性。例如使用3行空行来表示方法的结束，没有空行或每行代码间都加空行却不利于代码美观。

3. 留意首行缩进。正确的缩进对于语义块来说就像括号和空行一样重要。

4. 限制每行的字符数，提高可读性。大多数程序员认可的限制数为80个左右。

5. 使用一致的空格，通常以下的这些情况要使用空格： 

//运算符和变量之间 
a += b , c = 0; (a == b)

//语句关键字和括号之间
if (value) {, public class A { 

//循环的“；”号后
for (int i = 0; i < length; i++) 

//类型和变量之间
(int) value , (String) value

英文原文：10 Best Practices for Code Commenting & Formatting
2
顶
1
踩
评论 共 7 条 请登录后发表评论
7 楼 diaozhanming 2013-02-01 18:40
fancyleeo 写道
keer2345 写道
这也能成一篇文章呀，   在IDE里自动格式化，什么都OK了，纠结那么多干嘛


1.自动格式化自动不了注释内容，该在哪加注释，加什么内容的注释，都是需要考虑的！
2.作者对格式的讨论中电是：有时IDE的格式化不一定符合公司的格式规则，所以需要有一些注意事项。

看清楚了再发表意见，OK？  

两位讨论的其实各有道理，可能是处于不同的编程环境之中，我们公司使用sonar去check你的代码，所以这方面的要求会比较严格,compliance必须达到90%。就第一位的方法，那么久应该所有人使用一样的template这样大家的风格会近乎一致，这是很好的习惯。另外就是eclipse有save action 可以保证每次保存之后代码会进行重新的整理，这样对大项目的管理有好处。对于注释，出了某些特殊的业务逻辑注释，其实可以选用jautodoc这个插件，可以节省很多加某些doc注释的时间，而且对代码中命名机制也会有矫正作用。
6 楼 dohkoos 2012-12-14 13:21
引用
为重要的且没有自文档化的变量写注释。

如果有这种变量，那么要做的不是为它写注释，而是重构该变量名使之易于理解。

不写，少些，写必要的注释。

格式化的话，使用工具CheckStyle就行了，大概差不离就可以，不要规定的太死。
5 楼 fancyleeo 2012-03-30 12:07
打错了，是重点~不是中电。
4 楼 fancyleeo 2012-03-30 12:07
keer2345 写道
这也能成一篇文章呀，   在IDE里自动格式化，什么都OK了，纠结那么多干嘛


1.自动格式化自动不了注释内容，该在哪加注释，加什么内容的注释，都是需要考虑的！
2.作者对格式的讨论中电是：有时IDE的格式化不一定符合公司的格式规则，所以需要有一些注意事项。

看清楚了再发表意见，OK？  
3 楼 fancyleeo 2012-03-30 12:04
need_faith 写道
单行注释“//”后应不应该有空格？


应该有！我一般都加个空格。

// This is a comment!

/* This is another comment
 * and another line. lol~
 */
2 楼 keer2345 2012-03-27 08:43
这也能成一篇文章呀，   在IDE里自动格式化，什么都OK了，纠结那么多干嘛
1 楼 need_faith 2012-03-27 08:32
单行注释“//”后应不应该有空格？

发表评论

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

相关推荐

  • RISC-V在快速发展的处理器生态系统中找到立足点

    例如，中国的RISC-V开发者社区报告说，开源Fedora中超过80%的软件包现在在RISC-V上得到了支持。 Some key packages, such as Pytorch, GCC, TensorFlow, and OpenJDK will work, but are not yet fully supported. ...

  • SM-G9008V Root，google框架安装 设置开发者模式

    不小心将自己手机的Root应用弄丢了，没办法获取到root权限，需要重新root，以前Root，修改ro-debuggable=1,刷google框架花费了大量的时间，考虑到以后可能还会...机型：三星 SM-G9008V 版本：G9008VZMU1BOJ4国行的手机

  • 前端学习笔记 - 移动端Web开发

    作为开发者无需关注这些分辨率，因为常用的尺寸单位是px 常见移动端屏幕尺寸 设备 尺寸(英寸) 开发尺寸(px) 物理像素比 iphone3G 3.5 320*480 1.0 iphone4/4s 3.5 320*480 2.0 iphone5/5s/5c 4.0 320*568 2.0 HTC ...

  • Unity-AR 简介

      ARCore提供了Android、Android NDK、Unity、Unreal开发包，ARKit官方只提供了Xcode开发包，这也提高了利用其他工具进行开发的开发者学习成本。在这种情况下，Unity构建了一个AR开发平台，这就是ARFoundation，...

  • MLPerf Benchmarks - MLPerf 基准测试

    However, machine learning is completely unlike conventional software - developers train an application rather than program it - and requires a whole new set of techniques analogous to the ...

  • 软件及其公司篇--项目管理（七）

    软件所属公司谷歌及开放手机联盟介绍：（来自百度百科） **谷歌公司（Google Inc.）**成立于1998年9月4日，由拉里·佩奇和谢尔盖·布林共同创建，被公认为全球最大的搜索引擎公司。谷歌是一家位于美国的跨国科技...

  • Android 计步器 - 手机自带系统级的 健康运动App 授权

    #1 手机自带系统级的 健康App；...比如：三星手机上的 “三星健康” ; 华为手机上的“运动健康”； 小米手机上的“运动计步” 魅族手机： 计步器 oppo： 运动计步 vivo：vivo手机不自带“记步数”功能的 ...

  • ARCore系列教程（1）---创建第一个原生AR应用

    AR全新教程专栏--【ARCore】帮助开发者了解如何使用ARCore在Android平台构建AR应用。 关于ARCore ARCore 是 Google 的增强现实体验构建平台。ARCore 利用不同的 API 让用户的手机能够感知其环境、理解现实世界并...

  • 计算机英语（31-60）

    通过使用Ajax，Web开发人员可以创建有效使用资源的交互式网站，并为访问者提供响应式界面。 32、Alert Box An alert box, sometimes called a message box, is a small window that pops up on your screen to...

  • 适用于Samsung Smart TV的Unity 4.5

    Take your games to Samsung Smart TV 将您的游戏带到Samsung Smart TV Hooray! Today, we’re pleased to announce the public preview of Unity 4.5 for Samsung Smart TV, adding another platform to Unity’s...

  • SylixOS入门指南--架设开发环境

    SylixOS源码众多，但风格统一，这主要归功于开发者们使用统一的代码风格来书写SylixOS系统， sylixos_preference.epf是我们配制的Eclipse代码样式文件，导入它来书写代码，我们就可以轻松地书写出符合SylixOS...

  • Xamarin Getting Started翻译系列五--Android资源

    Android资源本文介绍XamarinAndroid中的Android资源概念，以及如何使用资源。讨论如何使用资源实现应用程序本地化，多种设备支持如各种屏幕大小和密度。This article introduces the concept of Android resourcesin...

  • Learn Some Framework-1

    为方便APP开发者或是Framework开发者浏览AOSP的source code， Google有架设OpenGrok服务器供大家查询使用，地址为： androidxref.com 登陆后在左侧选择你需要浏览的Android的大版本号即可查看platform的source code...

  • 【TA-霜狼_may-《百人计划》】图形3.7 移动端TP（D）R架构

    【TA-霜狼_may-《百人... 提倡使用模型LOD，本质上减少FrameData的压力，Unity中尽早在应用阶段借助umbra遮挡剔除 参考目录 [GPU性能指标 ] https://www.gpuinsight.com/gpu_performance/ [三星的GPU-FrameBuff指导] ...

  • 转：Oculus Unity Development Guide开发指南(2015-7-21更新)

    tid=34175 Oculus Unity Development Guide开发指南转载请保留原始地 http://t.cn/RAblKohOculus/GearVR开发者群302294234Welcometo the Unity Development Gui...

  • 【翻译】(63)supports-gl-texture元素

    每当你上传一个应用程序到Android市场发布者网站时，Android市场扫描应用程序的清单文件并寻找任意&lt;supports-gl-texture&gt;元素。它从元素中抽取格式描述符并内部地存储它们作为与应用程序.apk关联的元数据以及应用...

  • Android---Android 4.0 Unifies Tablets and Phones with New Features .

    ShareActionProvider部件允许开发者为他们的应用添加共享的功能。 媒体： 基于Khronos OpenMAX AL 1.0.1的多媒体流API，在流媒体内容方面提供了更多控制权。相机支持ZSL曝光，连续对焦，图像缩放，捕捉全...

  • IPHONE6 近来1年不会开放NFC的API给开发者，也就是只能用来做支持了现在

    IPHONE6 近来1还不会开放NFC的API给开发者，也就是只能用来做支持了现在,但是可以肯定的是，以后肯定会放发出来的，就像指纹传感器一样，现在也开放出来了，前面5S的时候，还也没有放出来，小伙伴们，峁足劲干吧！...

  • VisionMobile：三星如何争取开发者了解健康数据

    2014年5月28日，visionMobile发表了How Samsung enlists developers to make sense of health data 三星公布了移动健康愿景。“您身体的声音”有两个革新：具有传感器的Simband设备作为下一代可穿

  • java+sql server项目之科帮网计算机配件报价系统源代码.zip

    sql server+java项目之科帮网计算机配件报价系统源代码

Global site tag (gtag.js) - Google Analytics