每天推荐一个 GitHub 优质开源项目和一篇精选英文科技或编程文章原文，欢迎关注开源日报。交流QQ群：202790710；微博：https://weibo.com/openingsource；电报群 https://t.me/OpeningSourceOrg

今日推荐开源项目：《从 Youtube 上下载 youtube-dl》传送门：GItHub链接

推荐理由：这是一个能让你通过命令行下载 Youtube 视频的项目，有了这个你就不需要去找提供 Youtube 下载的别的网站了，它还提供了很多（非常多）的设置，如果你有特殊的需求的话可以去那一大堆设置里面找一找兴许能找到……大概。顺带一提，在用这个下载之前，上 Youtube 还是要各位各凭本事的。

今日推荐英文原文：《Do code comments suck?》作者：Sam Fare

原文链接：https://medium.com/@samuel.fare/do-code-comments-suck-abd99103c45a

推荐理由：给你的代码写注释！没有注释的代码真的很难看懂，但是有的时候，比起写注释，从最开始给变量或者函数起个简单易懂的名字更为重要。

Do code comments suck?

What is a comment?

A comment is a line in your source code file that can be read by developers but is ignored by compilers and interpreters.

What’s the point of that?

Code is often hard to understand. Adding descriptive text allows developers to explain their code to those who will maintain the code afterwards.

Need proof? Take the uncommented code below:

let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);
game.v_Add(bg_a);

This block of code does several things. The result is that it is difficult for programmers to easily understand what it does.

Now consider the same code with comments.

 // create the alien object.
let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");

// set Alien details.
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);

//add to game
game.v_Add(bg_a);

Doesn’t this seem so much easier to understand than before the comments were added? This is because a comments describe what the code is doing. whereas the code is describing how it is happening.

As developers we like to think in ‘what’s and not ‘how’s.

So comments help us clarify our code?

Yes.

That sounds like a good thing…

Yes it is. However there are many ways to clarify our ideas in code. Of these ideas, comments are the worst.

So what makes comments ‘the worst’?

Well there are a few things. The first is that there is no guarantee that someone will read them. In fact, most developers just don’t bother. Our tooling is even against us. Take a look at this Webstorm screen cap. The default colour scheme makes comments a light easy-to-ignore grey:

Some code with a hidden comment.

So why not just write a blog called ‘Please Read Comments’?

That’s a good question. It’s because you can’t trust the comments you read.

The executable code you write is a source of truth. We know it’s true because we are actually running it. Comments are an alternative source of truth but there is nothing to guarantee the truthfulness of them.

Just like any other system where there are multiple sources of truth it is common for a developer to update one source and forget to update another. Can you honestly say that when you change code you read through all the surrounding comments to ensure that they remain correct?

Well no, it’s an easy thing to forget.

Exactly. So always make sure your systems have one source of truth.

Ok I accept, comments aren’t perfect. Nothing in this world is. Are you saying you have a better plan?

Yes. You show me your comment, and I’ll show you a better alternative.

What about a comment that describes what a variable is, are you saying that it isn’t good to clarify what your variables are for?

Clarifying what variables do is super important. That’s why we give them names. If you give your variable a meaningful name then you have no need for a comment. Better still, every place that the well-named variable is used the maintainer of your code is reminded what it’s for. There’s no need to stop reading and refer back to it’s definition. Look how much nicer the second code is.

// Bad.
let x; // Variable to hold id of car being displayed.

// Good.
let displayedCarId;

This applies to functions too doesn’t it?

Yes. Give functions and their parameters names that describe what they do. If you do that, there will be no need for a function header style comment.

So what about your code from earlier, those comments describe blocks of code that achieve functionality together. That can’t be helped by good naming, can it?

Yes it can. A few lines of code that do one thing together can be extracted into well named functions. Have a look:

let alien = alienFactory
              .createAlien()
              .withStats({
                  health: 100,
                  armor: 50,
                  attack: 50
                })
              .getAlien();

game.add(alien);

See how the code to create an alien is now in a function that describes what it does? Same story with the stats code. The code above needs no further explanation, it does what it says.

Using a function here also has the advantage that details are hidden. The maintainer doesn’t have to worry about how the functions work if it’s not relevant to the particular change that they are making.This makes the code easier to understand.

The maintainer also can’t ignore the function name as they might ignore a comment. The function name is the code and thus to read the code they must read the function call and the function name.

So what about if I have to heavily optimise some code, can I use comments then?

Yes.

Wait, what?

We are Software Engineers. Engineers have tools. Comments are tools, so are functions, so are variable names. No tool fixes every problem. No tool is completely redundant. When the code can’t be improved through structuring it in a way that makes it understandable, comments are the best choice.

So comments are good?

No, comments suck! Most comments that I see in the wild are inappropriate. In particular comments are used as an excuse for:

Bad naming of variables or functions.
Excusing functions for being too long or too complex.

However the rule that comments suck is a rule of thumb not a absolute. There are rare uses for comments too.

youtube-dl

2018年8月8日：开源日报第153期