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

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


1.  程序注释

    程序注释的原则如下:

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

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

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

2. 文件注释

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

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

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

    2)必须包含作者

    3)必须包含项目名称

    4)必须包含文件名称

    5)可以包含书写日期

    6)可以包含版本信息

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

3. 类/接口注释

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

4.  方法和函数注释

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

 

相关文章推荐

团队项目开发"编码规范"之三:程序注释

发布日期:2011年3月18日星期三作者:EricHu   勤能补拙、笨鸟先飞。 3.1 注释概述 1、修改代码时,总是使代码周围的注释保持最新。 2、在每个例程的开始,提供标准的注释样本以指...

阿里java编码规范(三)控制语句,注释规约

最近阿里出了一个java开发手册,里面涉及到很多工作规范的地方,有很多借鉴和参考的作用,也可以给新入行的工程师作为参考。 下载地址是在:http://techforum-img.cn-hangzho...

C编码规范 注释 命名规则

  • 2014年01月14日 08:27
  • 74KB
  • 下载

PL/SQL编码规范: 注释、变量命名、书写格式、逻辑分支、 循环处理

1. PL/SQL编码规范 PL/SQL对大小写不敏感,故切忌使用大小写区分变量和其它用户定义的元素。为使代码具有可读性,可遵循以下简单的大小写规则以便在源代码中区分这些元素: ²        ...

《Google Java编程风格指南》代码注释与编码规范~总结

一:术语 1、术语class可表示一个普通类,枚举类,接口或是annotation类型(@interface)。 2、术语comment只用来指代实现的注释(implementation comm...

【学习笔记】JavaScript编码规范- 注释

多行注释使用/**……*/,需要包含一个描述,所有参数的具体类型的值还有返回值。 // bad // make() returns a new element // based on the pass...

C++编码规范(1):代码注释

C++编码规范(1):代码注释 C++编码规范(2):命名规范   当你阅读别人的代码时如果没有注释那会是件比较痛苦的事.一说到注释我们马上想到是通过//或/* */这样来添加一些描述信息.这只...
  • weiwenhp
  • weiwenhp
  • 2013年01月09日 15:20
  • 21581

java主类结构、基本数据类型、 变量与常量、运算符、数据类型转换、代码注释与编码规范

基本数据类型 在eclipe下依次创建项目,创建包,创建类。在类体重输入一以下内容: package a; public class test { static String s1="你好"; ...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:编码规范(三)之注释规范
举报原因:
原因补充:

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