1. 首页
  2. 分享

Linus Torvalds推荐的 内核注释 格式

上午看了一篇文章,Linux作者Linus Torvalds不知何故对注释开起炮来,暂且来看看他的观点 译文如下: 能不能不要再有这么傻X的注释风格了,拜托。

传统意义上对称式的C语言风格的多行注释相当得好,如果不使用,而是用不对称的形式。还不如干脆去用C++得了。

其实,有三种好的注释形式: (a) /* This is a comment *./

(b) /*

  • This is also a comment, but it can now be cleanly
  • split over multiple lines */

© // This can be a single line. Or many. Your choice.

显而易见,这三种注释形式看上去都很匀称。有时,你想将(b)变成单行模式,加入 一些空白以使得注释更为醒目,但是想要变成(c)形式,可以在注释前后加入两个空行。 (c)模式很适合放在结构体或者枚举成员的后面来注释,这些位置有对齐成员变量的需求,但是,这种结尾注释也会使人眼花缭乱。

在别的代码中,也有一些惯用的多行注释风格,但这不是常用的内核风格。 (d) /* This is an alternate multi-line format that isn’t horrible, but not kernel style */

原文如下: Re: [patch] crypto: sha256-mb - cleanup a || vs | typo

From: Linus Torvalds Date: Fri Jul 08 2016 - 13:19:42 EST Next message: Michael Turquette: "Re: [PATCH 2/2] arm64: dts: set UART1 clock frequency to 150MHz" Previous message: Tim Chen: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" In reply to: Tim Chen: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" Next in thread: Geert Uytterhoeven: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" Messages sorted by: [ date ] [ thread ] [ subject ] [ author ] [ rare comment rant. I think I’ll do this once, and then ignore the discussion ]

On Fri, Jul 8, 2016 at 9:45 AM, Herbert Xu <herbert@xxxxxxxxxxxxxxxxxxx> wrote:

Nack. As I said the commenting style in the crypto API is the same as the network stack. So unless we decide to change both please stick to the current style.

Can we please get rid of the brain-damaged stupid networking comment syntax style, PLEASE?

If the networking people cannot handle the pure awesomeness that is a balanced and symmetric traditional multi-line C style comments, then instead of the disgusting unbalanced crap that you guys use now, please just go all the way to the C++ mode.

In other words, these three models are good:

(a) /* This is a comment *./

(b) /*

  • This is also a comment, but it can now be cleanly
  • split over multiple lines */

© // This can be a single line. Or many. Your choice.

and they are all obviously visually balanced. Sometimes you want (b) even for a single line, if you want the white-space to make it stand out more, but you can obviously do that with © too, by just surrounding it with two empty (comment) lines.

The © form is particularly good for things like enum or structure member comments at the end of code, where you might want to align things up, but the ending comment marker ends up being visually pretty distracting (and lining that up is too much make-believe work).

There’s also another acceptablr traditional multi-line style that you’ll find in some places, but it’s not the common kernel style:

(d) /* This is an alternate multi-line format that isn’t horrible, but not kernel style */

Note how all the above comment styles have a certain visual symmatry and balance.

But no, the networking code picked none of the above sane formats. Instead, it picked these two models that are just half-arsed shit-for-brains:

(no) /* This is disgusting drug-induced

  • crap, and should die */

(no-no-no) /* This is also very nasty

  • and visually unbalanced */

Please. The networking code actually has the worst possible comment style. You can literally find that (no-no-no) style, which is just really horribly disgusting and worse than the otherwise fairly similar (d) in pretty much every way.

I’m not even going to start talking about the people who prefer to "box in" their comments, and line up both ends and have fancy boxes of stars around the whole thing. I’m sure that looks really nice if you are out of your mind on LSD, and have nothing better to do than to worry about the right alignment of the asterisks.

I’d be happy to start moving the whole kernel over to the C++ style, it’s been many many years since we had compatibility issues and we are all used to it by now, even if we weren’t all fans originally.

I really don’t understand why the networking people think that their particularly ugly styles are fine. They are the most visually unbalanced version of all the common comment styles, and have no actual advantages.

So just get rid of the (no-no) and (no-no-no) forms. Not in one big go, but as people touch the code, just fix that mess up.

Linus

Next message: Michael Turquette: "Re: [PATCH 2/2] arm64: dts: set UART1 clock frequency to 150MHz" Previous message: Tim Chen: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" In reply to: Tim Chen: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" Next in thread: Geert Uytterhoeven: "Re: [patch] crypto: sha256-mb - cleanup a || vs | typo" Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

收藏

暂无评论

登录后可以进行评论。没有账号?马上注册