不必要的注释

良好代码的优点大同小异。

不好的代码的糙点却各有巧妙之处。

注释

代码撰写，最终的目标是希望可以记载知识，提供阅读与维护。

好的代码，可以像文件化（文件一样，自己解释自己），不过程式语言中的语法，有它的极限，只是人类脑中想表达的方式却是各式各样的。

在代码中，注释的正确使用方式，是能够在最关键时刻，提供提示的内容。

但是有个重要的前提，就是要先懂得尽可能的使用程序语言的语法表达，也尽可能的读懂程序语言的语法与语意。

这是一段可以自我说明的PL/I程序+它的注释[1]

语法本身无法表达的程序流程，在最后用注释辛苦的画上箭头，提示开发者重要的信息。

不适合使用注释的情境

该用function name取代注释(qsxxfj)

来看看一段代码[2]，给自己五秒钟看看是不是可以一眼就看出这在做什么？

function main（）{

//openImage

const img = document.querySelector（“img”）；

const canvas = document.querySelector（“#draw”）；

var ctx = canvas.getContext（“2d”）；

const height = img.height；

const width = img.width；

canvas.width = width；

canvas.height = height；

ctx.drawImage（img，0，0，width，height）；

const image = ctx.getImageData（0，0，width，height）；

//imageProcess

const threshold_input = document.querySelector（'#threshold'）；

threshold = threshold_input.value；

for（let i = 0；i < image.data.length；i += 4）{

let sum = image.data[i + 0] + image.data[i + 1] + image.data[i + 2]；

let color = sum / 3；

if（color > threshold）{

color = 255；

}

else {

color = 0；

}

image.data[i + 0] = color；// RED

image.data[i + 1] = color；// GREEN

image.data[i + 2] = color；// Blue

}

// report

let [countW，countB] = countWB（image）；

showReport（countW，countB）；

console.log（countW /（countW + countB）* 100，countB /（countW + countB）* 100）；

// drawImage

const canvas = document.querySelector（“#draw”）；

var ctx = canvas.getContext（“2d”）；

ctx.putImageData（image，0，0）；

}

img.addEventListener（'load'，main）；

看得出来吗？

还是你喜欢看这个版本？

function main（）{

let image = openImage（“img”，“#draw”）；

image = imageProcess（image）；

report（image）；

drawImage（image，“#draw”）；

}

先前有提过，曝露太多复杂性的问题，而复杂有段落感、有层次感需要表达。

在此的第一个例子，就是用注释呈现段落感，但是这并不是一个使用注释的好时机，段落感最好的做法，用function name取代注释。

而简要的说明自己的代码在做什么，在这个例子，就是要把主程式的内容说一次。

做了四件事情

打开图档

图像处理算法

显示图像处理结果的量化数据

显示图像处理结果的图形数据

分别再往内细讲每一个步骤在做什么。

打开图档

宣告好canvas

取得img tag的图像来源

图像处理算法

设定阀值

处理每一个pixel

比阀值大，就变白，不然变黑

显示图像处理结果的量化数据

计数黑白值各多少

显示计算结果到画面上

显示图像处理结果的图形数据

图像结果显示在canvas上

是不是很像用文书编辑时的大纲模式，这就是层次感

程序语言要写得不糙，最基本的，就是要注意层次与段落的安排。

在此，不要靠注释。

「注释会说谎，原始码不会」

--感谢海绵宝宝的补充

注释不要解释语法

如果你的程序注释，总是这样写，代表几件事

你没有进步。

很勤劳（但不是好的那种）

不擅长与人有效的沟通

function openImage（img_tag，canvas_id）{

const img = document.querySelector（img_tag）；//取得img

const canvas = document.querySelector（canvas_id）；//取得canvas

var ctx = canvas.getContext（“2d”）；//宣告出canvas的2d context

//决定img长宽

const height = img.height；

const width = img.width；

//定义canvas长宽与img相同

canvas.width = width；

canvas.height = height；

// context由canvas的左上开始，画出img的长宽的大小，画出img内容

//就是显示img到canvas

ctx.drawImage（img，0，0，width，height）；

//回传img的pixel data

return ctx.getImageData（0，0，width，height）；

}

这些注释都是语法本身，也就是说，所有的内容都重复了两次，对于语法纯熟的开发者来说，只是赘字[3]而认真要说，是一种语病，要小心！！！(qsxkgz)