别给糟糕的代码加注释——重新写吧
若编程语言有足够的表达力,就不那么需要注释——也许根本不需要。
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败,注意,失败。注释总是一种失败,我们总找不到不用注释就能表达自我的方法,总要有注释,这并不值得庆贺。每次写注释,你都该做个鬼脸,感受自己在表达能力的失败。
注释不能美化糟糕的代码,与其花时间编写解释你搞出的糟糕代码的注释,不如花时间清洁那堆糟糕的代码,写出整洁而有表达力的代码。
好注释
- 法律信息
有时,公司代码规范要求编写与法律有关的注释。IDE会自动卷起这些注释
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
对意图的解释。
有时候稍微解释一下,自己某段程序准备做什么操作。提供信息的注释
// 格式化匹配的 kk.mm.ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
"\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*" );
也可以把这段代码移动到某个时期和时间格式的类中,可能会更好和更清晰。
警示
// 除非你必须要杀掉某些东西,否则则不要运行这段程序TODO 注释
// TODO是一种程序员认为应该做,但是由于某些原因目前还没有做的工作。
目前,大多数好IDE都提供了特别的手段来定位所有的TODO注释。说明重要性
// 本次操作非常重要,它去除了字符串两边的空格
如果你决定写注释,那么就花必要的时间确保写出最好的注释。
坏注释
喃喃自语
多余的注释,废话的注释。
误导性注释
循规蹈矩式注释
例如,要求每个函数都要写javadoc,就会得到很多原本无需写注释的注释。能用函数或变量时就别用注释。
位置标记
有点程序员喜欢在源代码中标记某个特别的位置。少用这种无理,鸡零狗碎的注释。
// Actions ///注释掉的代码。
有些已经不用的程序,依然被注释在哪里,有的人可能回想代码留在哪里也许会有用。但是我们现在有源代码控制系统,无需再用注释来标记,删掉即可。
最后
还是要记住,写程序不仅仅是为自己而写,考虑到读到你写的代码时的感受。不要喃喃自语,清晰的用程序语言表达自己