编码规范(三)之注释规范

原创 2015年07月07日 21:06:12


1.  程序注释

    程序注释的原则如下:

        写在被注释代码前面,而不是后面,但对于单行语句,按照习惯可以把注释放在语句的末尾。

        对于大段注释,使用/**/格式,通常在文件和函数注释中使用,而代码内部统一使用//注释,因为其写起来简单。

        注释不必太多,大家都看得懂的行不必注释。

2. 文件注释

    文件注释通常放在整个PHP文件头部,其内容包括文件版权、作者、编写日期、版本号等重要信息。PHP中,可以参照phpdocument规范,便于利用程序自动生成文档。

    文件注释需要包含以下规则:

    1)必须包含本程序的概述

    2)必须包含作者

    3)必须包含项目名称

    4)必须包含文件名称

    5)可以包含书写日期

    6)可以包含版本信息

    7)可以包含重要使用说明。

3. 类/接口注释

    类/接口的注释应该尽量简洁。按照一般的习惯,一个文件只包含一个类,在注释中通常不需要再加上作者和版本信息,加上可见性和简单的描述即可。如果文件注释已经足够详细。可以不用各类注释。如果同时存在接口和接口的实现类,只需要给接口中加注释。

4.  方法和函数注释

    方法和函数注释写在前面,通常需要标明的信息主要是可见性、参数类型和返回值的类型。

 

需要区分在接口方法注释和方法实现的注释.

前两天负责review 一些代码, 这些代码的质量都是非常好的, 而且注释也非常的清晰. 不过发现一个问题,  在一个接口的实现类中, 其方法的注释也详细的说明该方法的功能和注意事项. 由于没有看到接...
  • loveyly
  • loveyly
  • 2007年11月26日 12:58
  • 3713

编码规范(三)之注释规范

1.  程序注释     程序注释的原则如下:         写在被注释代码前面,而不是后面,但对于单行语句,按照习惯可以把注释放在语句的末尾。         对于大段注释,使用/**/格式...
  • u012675743
  • u012675743
  • 2015年07月07日 21:06
  • 426

PHP框架Yii编码规范

PHP框架Yii编码规范 文件方法命名   文件名即类名 类名称: 驼峰式 首字母大字 class PointController class PointRatioController ...
  • wlzx120
  • wlzx120
  • 2016年09月22日 09:50
  • 382

Yii2 核心代码编码规范 (PSR 拓展)

yii2的核心代码的编码规范
  • wishy123
  • wishy123
  • 2015年05月15日 08:39
  • 1321

软件接口API规范

软件接口API规范                                                                                     ...
  • foxfile_hom
  • foxfile_hom
  • 2018年01月31日 10:57
  • 16

Java注释规范

Java注释规范 2007年03月27日 星期二 14:01 Java代码规范 --注释 @author LEI @version 1.10 2005-09-01 1 注释...
  • ID_Rin
  • ID_Rin
  • 2017年01月06日 18:15
  • 1266

python 基础知识汇总(注释规范)

1.python的注释规范 python 分为 单行注释,多行注释以及特殊注释 特殊注释: #!/usr/bin/env python # -*-coding:utf...
  • liuxiaohua23
  • liuxiaohua23
  • 2018年01月31日 16:49
  • 34

AlloyTeam代码规范

欢迎使用Markdown编辑器写博客本Markdown编辑器使用StackEdit修改而来,用它写博客,将会带来全新的体验哦: Markdown和扩展Markdown简洁的语法 代码块高亮 图片链接和...
  • u012089073
  • u012089073
  • 2017年01月10日 00:13
  • 832

java代码注释规范

代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范...
  • shiyuezhong
  • shiyuezhong
  • 2012年11月20日 20:20
  • 145924

javadoc注释规范

javadoc注释规范 javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。 javadoc命令是用来生成自己A...
  • lovelichao12
  • lovelichao12
  • 2017年10月19日 14:18
  • 131
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:编码规范(三)之注释规范
举报原因:
原因补充:

(最多只允许输入30个字)