about blog github

01 Jul 2017
coding感想(二)

coding感想(一)之后,有了这篇coding感想(二),主要是因为最近几天接触了一些比较“生猛”的代码,所以想借助本文总结下,本次分享主要有以下4个方面:

  • 代码中的空格和空行
  • 代码中的注释
  • 代码中的数字
  • 代码中的日志

1)代码中的空格和空行

某天上班时,看了一些代码,我忍不住发了一条朋友圈,内容如下:

写代码时,空格和空行真的很重要。

真的没忍住,最基本的布局意识和美感都没有,函数定义之间一行挨着一行,逻辑判断从左写到右,运算符和变量之间没有一个空格,代码块之间也没有用空行分隔下,看得人头晕眼花。就像公司某技术大神说的一样,看到那样的代码,不先格式化一下,心里是拒绝维护这样的代码的。空格和空行都写不好,还指望能写好代码,我觉得有点不太可能。程序员写的代码是要给人读的,不是给机器读的,这个别人也许是6个月后的你,代码是需要不断维护的,人都读不懂,何谈维护。实在不知道如何布局,用什么语言,就去看看该语言的标准库是如何布局的。

2)代码中的注释

代码看多了,多少会看到一些“无脑”注释,比如:

// get host name
func getHostName() {

}

// initialize environment
func initEnv() {

}

函数名已经自注释了,还多此一举,废话连篇。最反感的就是这类注释,写代码的人就是为了注释而注释,一点都不动脑子。我看到这类注释,一般就是直接删除或者修改变量名,把更多信息装到名字里面。比如下面这个注释:

// download page
func getPage(url string) {

}

改成这样就更易读:

func downloadPage(url string) {

}

根本没有必要写那多余的注释,如果名字不能承载更多的信息,才想到通过注释来解释这段代码,而不是随意取一个名字,然后又通过注释来说明代码的意图。阅读这样的代码无形中就增加了代码维护人员理解这段代码所需时间。我的建议是,尽量让代码自注释,即代码易读易懂。除非真的有必要,才写注释,但是写注释之前我都会考虑下是不是命名不够准确。注释太多也是需要花时间维护的,如果代码的逻辑改变了,但是注释没有更新,就不好玩了。不要忘记注释的目的,是为了别人或者自己更快速的理解代码意图,而不是空写一些无意义的注释。

3)代码中的数字

在读代码时,经常看到一些数字,不联系上下文仔细看,硬是不知道数字代表什么意思。比如下面的代码:

update_interval = 5

这里的数字5到底代表什么意思。表示更新间隔是5秒?还是表示更新间隔是5个小时?又或者5天?可能有时候就算联系上下文也未必知道这个数字5到底是什么意思。所以,我建议在代码中只要出现一些难以理解的数字,尽量取一个易读易懂的名字,或者添加必要的注释。比如上面的例子可以通过以下方式得到改善:

update_interval_seconds = 5

or

TIME_SECOND = 1
update_interval = 5 * TIME_SECOND

4)代码中的日志

调试过代码的人都知道,如果程序打印的日志详细且合理,只要一看日志就能大概知道问题出在哪,能大大节省代码的调试时间。比如,一个程序在创建文件时由于磁盘空间已满,创建文件失败,那么这时候打印一条“由于磁盘空间已满,创建文件失败”的日志就很有必要。否则,当你试着在自己环境重现该问题时,如果你磁盘空间未满,估计永远也重现不出该问题,更谈不上解决问题了。另外,日志的打印会根据不同的场景而选择不同的日志级别,常见的日志级别有以下6种:

  • info: 打印一般描述信息,表示程序运行的过程,该类信息可能面对最终用户,需要谨慎
  • debug:打印程序的调试信息,只要是对调试有帮助的信息都可以通过该级别打印,一般程序正式发布后就不打印该级别日志
  • trace:比debug级别的粒度更细,追踪程序的运行状态
  • warn: 打印警告信息,表明程序运行有潜在错误,需要引起注意
  • error:打印错误信息,程序一般还可以继续运行,但是应该引起注意
  • fatal:打印严重错误信息,程序一般都需要退出,否则继续运行会导致更严重的错误

所以,写代码时要根据不同的场景打印不同级别的日志,以便未来方便维护。当然,日志不是越多越好,日志打印太多,会有性能影响,但是如果没有日志,那也是万万不行的。

本次分享就到这里,下次再继续~

本次荐书:未来简史

未来简史



LEo at 19:56

about blog github