每天推薦一個 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期