悬挂缩进什么意思(论文参考文献悬挂缩进什么意思)

注释应该陈述代码的高级意图，而不是显而易见的细节。

反例

public static String generateSignature(Map<String, Object> params, String secret) throws Exception { final StringBuilder paramStr = new StringBuilder(); final Map<String, Object> sortedMap = new TreeMap<>(params); for (Map.Entry<String, Object> entry : sortedMap.entrySet()) { paramStr.append(entry.getKey()); paramStr.append(entry.getValue()); } Mac hmac = Mac.getInstance("HmacSHA1"); SecretKeySpec sec = new SecretKeySpec(secret.getBytes(), "HmacSHA1"); hmac.init(sec); byte[] digest = hmac.doFinal(paramStr.toString().getBytes()); return new String(new Hex().encode(digest), "UTF-8"); }

解释

上面的方法是用来根据参数生成签名的，评论里详细描述了签名算法的实现步骤，实际上是过度描述了代码明显的细节。

正面例子

public static String generateSignature(Map<String, Object> params, String secret) throws Exception { final StringBuilder paramStr = new StringBuilder(); final Map<String, Object> sortedMap = new TreeMap<>(params); for (Map.Entry<String, Object> entry : sortedMap.entrySet()) { paramStr.append(entry.getKey()); paramStr.append(entry.getValue()); } Mac hmac = Mac.getInstance("HmacSHA1"); SecretKeySpec sec = new SecretKeySpec(secret.getBytes(), "HmacSHA1"); hmac.init(sec); byte[] digest = hmac.doFinal(paramStr.toString().getBytes()); return new String(new Hex().encode(digest), "UTF-8"); }

摘要

注释一定是表达代码之外的东西，代码可以包含的内容，注释中一定不要出现如果有必要注释，请注释意图（why），而不要去注释实现（how)，大家都会看代码

在文件/类级别使用全局注释来解释所有部分是如何工作的。

正面例子

public class SystemUtils {}

摘要

通常，每个文件或类都应该有一个全局注释来概括该类的角色。

公共api需要添加注释，其他代码慎用注释。

反例

public interface KeyPairService { PlainResult<KeyPairInfoModel> createKeyPair(KeyPairCreateParam createParam);}

解释

上述接口提供的Dubbo rpc服务属于公共api，以双方包的形式提供给调用者，虽然代码简单，缺乏接口大纲描述、方法注释等基本信息。

正面例子

public interface KeyPairService { PlainResult<KeyPairInfoModel> createKeyPair(KeyPairCreateParam createParam);}

摘要

公共api必须有注释，类文件使用类注释，公共接口方法使用方法注释。

在评论中用精心挑选的输入和输出例子来解释。

正面例子

public static boolean contains(final CharSequence seq, final int searchChar) { if (isEmpty(seq)) { return false; } return CharSequenceUtils.indexOf(seq, searchChar, 0) >= 0; }

摘要

为公共方法提供输入和输出的例子，尤其是通用工具方法，往往比任何语言都强大。

注释必须描述最接近它的代码。

反例

private Map<String, String> buildInstancedocumentMap(String version, String instanceId) { Map<String, String> instancedocumentMap = Maps.newlinkedHashMap(); Map<String, String> instancedocumentMapmetadataPart = metaDataService.getInstancedocument(instanceId, version, instancedocumentmetaKeys); instancedocumentMap.putAll(instancedocumentMapmetadataPart); //the map must remove the old key for instance type instancedocumentMap.put("instance-type", instancedocumentMap.get("instance/instance-type")); instancedocumentMap.remove("instance/instance-type"); return instancedocumentMap; }

解释

该方法有一行从地图中删除数据的代码，注释放在put调用之前，但不直接放在remove之前。

正面例子

private Map<String, String> buildInstancedocumentMap(String version, String instanceId) { Map<String, String> instancedocumentMap = Maps.newlinkedHashMap(); Map<String, String> instancedocumentMapmetadataPart = metaDataService.getInstancedocument(instanceId, version, instancedocumentmetaKeys); instancedocumentMap.putAll(instancedocumentMapmetadataPart); instancedocumentMap.put("instance-type", instancedocumentMap.get("instance/instance-type")); //the map must remove the old key for instance type instancedocumentMap.remove("instance/instance-type"); return instancedocumentMap; }

摘要

注释应放在离其描述代码最近的位置。

注释必须与代码相对应。

反例

public static String randomStringWithId(int len, long id) { if (len < 1 || len > 32) { throw new UnsupportedOperationException("can't support to generate 1-32 length random string"); } //use default random seed StringBuffer sb = new StringBuffer(); long genid = id; for (int i = 0; i < len; i++) { long pos = genid%32 ; genid = genid>>6; sb.append(RANDOM_CHAr[(int) pos]); } return sb.toString(); }

解释

注释中写明生成的随机字符串长度不能超过16个字符，但实际代码已经修改为32个字符。这里的注释会产生误导读者的副作用。

正面例子

public static String randomStringWithId(int len, long id) { if (len < 1 || len > 32) { throw new UnsupportedOperationException("can't support to generate 1-32 length random string"); } //use default random seed StringBuffer sb = new StringBuffer(); long genid = id; for (int i = 0; i < len; i++) { long pos = genid%32 ; genid = genid>>6; sb.append(RANDOM_CHAr[(int) pos]); } return sb.toString(); }

摘要

注释一定要与代码对应，通常代码变化对应的注释也要随之改变若非必要慎用注释，注释同代码一样需要维护更新

一定要注释常量。

反例

public final class CommonConstants { private CommonConstants() {} public static final String BILLING_BID = "26842"; public static final int BILLING_DOMAIN_INTEGRITY_VALID = 1; public static final int BILLING_READYFLAG_START = 0;}

正面例子

public final class CommonConstants { private CommonConstants() {} public static final String BILLING_BID = "26842"; public static final int BILLING_DOMAIN_INTEGRITY_VALID = 1; public static final int BILLING_READYFLAG_START = 0;}

摘要

给每一个常量加一个有效的注释

用聪明的标记(TODO，FIXME，HACK)

TODO 有未完成的事项FIXME 代码有已知问题待修复HACK 表示代码有hack逻辑

例子

public static String randomStringWithId(int len, long id) { // TODO: 2018/6/11 需要将len的合法范围抽象 if (len < 1 || len > 32) { throw new UnsupportedOperationException("can't support to generate 1-32 length random string"); } //use default random seed StringBuffer sb = new StringBuffer(); long genid = id; for (int i = 0; i < len; i++) { long pos = genid%32 ; genid = genid>>6; sb.append(RANDOM_CHAr[(int) pos]); } return sb.toString(); }

配置标记

您可以扩展IDE来修改标记的配置，例如添加诸如解算器和相关缺陷之类的信息。以IDEA为例，修改条目如下:

什么意思(论文参考文献悬挂缩进什么意思)插图" class="j-lazy" src="/uus/1529681005774b4565b2748~tplv-tt-large.png" img_width="640" img_height="390" inline="0" alt="代码整洁之道——优雅注释之道">

摘要

巧用TODO、FIXME、HACK等注解标识代码及时处理所有标识代码，忌滥用

添加适当的警告注释。

正面例子

private baseResult putReadyFlag(BillingDataContext context, Integer readyFlag) { // warn! oms data format require List<Map<String,String>> and the size of it must be one. List<Map<String, String>> dataList = Lists.newArrayListWithExpectedSize(1); }

解释

该方法创建固定大小1和类型的地图

摘要

代码中偶尔会出现一些非常黑的逻辑，修改会造成很高的风险。这时候就需要添加评论来强调了。

注释代码

反例

private Object buildParamMap(Object request) throws Exception { if (List.class.isAssignableFrom(request.getClass())) { List<Object> input = (List<Object>)request; List<Object> result = new ArrayList<Object>(); for (Object obj : input) { result.add(buildParamMap(obj)); } return result; } Map<String, Object> result = new linkedHashMap<String, Object>(); Field[] fields = FieldUtils.getAllFields(request.getClass()); for (Field field : fields) { if (IGNORE_FIELD_LIST.contains(field.getName())) { continue; } String fieldAnnotationName = field.getAnnotation(ProxyParam.class) != null ? field.getAnnotation( ProxyParam.class).paramName() : HttpParamUtil.convertParamName(field.getName()); //Object paramValue = FieldUtils.readField(field, request, true); //if (paramValue == null) { // continue; //} // //if (BASIC_TYPE_LIST.contains(field.getGenericType().getTypeName())) { // result.put(fieldAnnotationName, String.valueOf(paramValue)); //} else { // result.put(fieldAnnotationName, this.buildParamMap(paramValue)); //} } return result; }

解释

常用的例程，为了方便重用废弃的代码，直接注释掉。

正面例子

同上，删除评论代码。

摘要

不要在代码中留下任何注释代码，不要把Git等版本管理软件能做的事情放到代码中。

常规注释

反例

public class DemoDO implements Serializable { private static final long serialVersionUID = -3517141301031994021L; private Long id; private Long aliUid; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public Long getAliUid() { return aliUid; } public void setAliUid(Long aliUid) { this.aliUid = aliUid; }}

解释

对上述代码的分析表明，有两个注释是笨拙和多余的:

类注释使用了默认模版, 填充了无效信息IDE为Getter及Setter方法生成了大量的无效注释

正面例子

public class DemoDO implements Serializable { private static final long serialVersionUID = -3517141301031994021L; private Long id; private Long aliUid; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public Long getAliUid() { return aliUid; } public void setAliUid(Long aliUid) { this.aliUid = aliUid; }}

摘要

不要保留任何循规蹈矩式注释，比如IDE自动生成的冗余注释不要产生任何该类注释，可以统一配置IDE达到该效果，推荐使用灵狐插件

日志注释

反例

String countryCode = param.getCountyCode(); if(StringUtils.isNotBlank(countryCode) && !"CN".equals(countryCode)){ imageOrderParam.setCountyCode(param.getCountyCode()); imageOrderParam.setCurrency(param.getCurrency()); }

解释

修改已有代码，很多人会手动添加注释，说明修改日期、修改人、修改描述等信息，大多是多余的。

正面例子

代码同上，删除此评论。

摘要

不要在代码中加入代码的文字信息，不要在代码中做版本管理能完成的事情。

“拐杖上的笔记”

反例

public Map<String, String> updateConfigWithSpecifiedKV(final String key, final String value) { if (StringUtils.isNotBlank(key) || StringUtils.isNotBlank(value)) { return Maps.newHashMap(); } Map<String, String> config = queryConfigMap(); if (MapUtils.isEmpty(config)) { return new HashMap<String, String>() {{ put(key, value); }}; } config.put(key, value); return config; }

解释

该代码简单地实现了更新指定的map k-v的函数。如果目标map不存在，它用指定的k-v初始化map并返回它。方法名为updateConfigWithSpecifiedKV。为了说明该方法的完整意图，注释描述了该方法的实现逻辑。

正面例子

public Map<String, String> createOrUpdateConfigWithSpecifiedKV(final String key, final String value) { if (StringUtils.isNotBlank(key) || StringUtils.isNotBlank(value)) { return Maps.newHashMap(); } Map<String, String> config = queryConfigMap(); if (MapUtils.isEmpty(config)) { return new HashMap<String, String>() {{ put(key, value); }}; } config.put(key, value); return config; }

摘要

抛弃“拐杖笔记”，不要给不好的名字加笔记。好名字比好笔记更重要。

过多的html注释

反例

@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)@documentedpublic @interface ProxyParam { String proxyApp() default "houyi"; String paramName(); boolean isRequired() default true;}

解释

类标注用了很多html标签来描述，实际效果并没有带来好处反而增加了阅读难度。

正面例子

@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)@documentedpublic @interface ProxyParam { String proxyApp() default "houyi"; String paramName(); boolean isRequired() default true;}

摘要

普通业务注释谨慎使用html标签，它不会给你带来明显收益，只会徒增阅读难度如果是公共api且用于生成javadoc可以考虑加入必要的html标签，比如链接，锚点等

爪哇

文件/类注释规范

目前，安装令狐后，IDE会自动将IDE的文件模板配置成以下格式:

_ _强烈建议使用上述配置。统一简洁是最好的。_ _如果有特殊需求，需要自定义班级评论，请参考下图:

方法注释

IDE提供统一的方法注释模板，无需手动配置。一个好的方法注释应该包括以下内容:

方法的描述，重点描述该方法用来做什么，有必要可以加一个输入输出的例子参数描述返回值描述异常描述

例如:

@Deprecated public static String toString(final byte[] bytes, final String charsetName) throws UnsupportedEncodingException { return charsetName != null ? new String(bytes, charsetName) : new String(bytes, Charset.defaultCharset()); }

块注释和行注释

单行代码注释使用行注释 //多行代码注释使用块注释

计算机编程语言

文件注释

重点描述文件的作用及使用方式#!/usr/bin/python# -*- coding: UTF-8 -*-"""bazaar script collection.init_resource_entry, used for init bazaar resource such as vpc, vsw, sg, proxy ecs and so on.user manual:1. modify ecs.conf config your key, secret, and region.2. run bazaar_tools.py script, this process will last a few minutes，then it will generate a init.sql file.3. use idb4 submit your ddl changes."""

类注释

""" ecs sdk client, used for xxx. Attributes: client: access_key: access_secret: region: """类应该在其定义下有一个用于描述该类的文档字符串类公共属性应该加以描述

函数注释

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ passArgs:列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数), 应该详细列出*foo和**bar.Returns: 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略Raises:列出与接口有关的所有异常

多行注释和行尾注释

# We use a weighted dictionary search to find out where i is in# the array. We extrapolate position based on the largest num# in the array and the array size and then do binary search to# get the exact number.if i & (i-1) == 0: # true iff i is a power of 2复杂操作多行注释描述比较晦涩的代码使用行尾注释

开发

行注释

常见注释样式

包注释

通常用于包注释，以整体提供该包的相应信息。每个包应该包含一个doc.go来描述它的信息。

package ecsproxy

Java script语言

常用的和//，用法基本和Java一样。

壳

仅支持#号，并且每个文件包含一个顶级注释来解释版权和摘要信息。

其他的

有待完善

总结

本文首先总结了编程中注释的最佳实践场景并举例说明，然后提供了一些注释模板和与不同编程语言规范相关的实践技巧。我个人对注释的理解是，注释是代码，注释是文档，写好注释是一个工程师必备的素质之一。在代码整洁的前提下，较少的注释是跟上高标准的追求。注释的做法暂时写到这里，以后会继续完善。也欢迎大家提供好的提示。本文中的大部分代码来自日常的业务项目，也有一部分摘自开源库。有不对的地方请指正。