English is not my mother tongue. However, I have to write comments in English. I want to improve my "comment English" by studying a piece of code which is commented in a good English. Please recommend an open source project which contains a lot of meaningful comments written by people with an excellent command of the language.
英语不是我的母语。但是,我必须用英文写评论。我想通过研究一段用英语评论的代码来改进我的“评论英语”。请推荐一个开源项目,其中包含很多有意义的评论,这些评论由具有出色语言能力的人编写。
7 个解决方案
#1
2
I can recommend Simon Tatham's Puzzle Collection.
我可以推荐Simon Tatham的Puzzle Collection。
The comments I've read look like correct English to me. Also, they're clearly written and contain useful information about why things are done the way they are.
我读过的评论看起来对我来说是正确的英语。此外,它们写得很清楚,并包含有关为什么事情按照它们的方式完成的有用信息。
The developer documentation is also easy to read and understand, and as a side benefit you'll be reading the documentation of a system with a good and simple architecture.
开发人员文档也易于阅读和理解,作为一个附带好处,您将阅读具有良好和简单架构的系统文档。
If you aim to read something and then emulate it without explicitly understanding why doing so is a good idea, I can definitely recommend ST's puzzles. If you want an explicit understanding of what good writing is, I think ST's puzzles will serve as a good example, but you really want to read something like Strunk and White.
如果你的目的是阅读某些东西,然后在没有明确理解为什么这样做是个好主意的情况下模仿它,我绝对可以推荐ST的谜题。如果你想要明确地理解好的写作是什么,我认为ST的谜题将作为一个很好的例子,但你真的想读一些像Strunk和White这样的东西。
#2
2
I don't think comments are a good place to learn, even if you have to emulate this style. Comments are often not even correct English and good projects will not have too many comments anyway, hence, not much to learn from.
我不认为评论是一个学习的好地方,即使你必须模仿这种风格。评论往往不是正确的英语和好的项目无论如何都不会有太多的评论,因此,没有太多的东西需要学习。
If, on the other hand, you take a project that is commented extensively you can be almost sure that it's not a great role model since the programmers were incapable of conveying terse meaning. This is a generalization, of course. However, I believe it's (almost?) always true. YMMV.
另一方面,如果你采用一个被广泛评论的项目,你几乎可以肯定它不是一个伟大的榜样,因为程序员无法传达简洁的含义。当然,这是一种概括。但是,我相信它(几乎?)总是如此。因人而异。
Instead, learn English by studying the experts. There has been a question about this. I recommended “On Writing Well” by William Zinsser and I will do so again.
相反,通过研究专家来学习英语。对此存在疑问。我推荐William Zinsser写的“On Writing Well”,我将再次这样做。
(By the way, English isn't my mother tongue either.)
(顺便说一句,英语也不是我的母语。)
#3
0
I've only ever looked at small pieces of it, but I hear the linux kernel is very well commented.
我只看过它的一小部分,但我听说linux内核得到了很好的评论。
#5
0
I fairly well commented open source project is Drupal . Check it at Drupal.org . I've developed several portals in it and you can actually learn quite a bit by reading comments in the modules and themes. Actually they are some times more informative then the documentation.
我相当好评论开源项目是Drupal。在Drupal.org上查看。我已经开发了几个门户网站,你可以通过阅读模块和主题中的注释来学到很多东西。实际上它们比文档更有用。
#6
0
Minix is quite well commented. They can be a bit terse in some places but the comments are very helpful.
Minix评论很好。它们在某些地方可能有点简洁,但评论非常有帮助。
#7
0
Also, if you want to improve your writing... There are a lot of confusing things about the english language. How you master these points is what distinguishes a mediocre writer from an excellent writer. The best, smallest, and most concise book to get (everyone should have a copy!) is called the Elements of Style by Strunk and White. Note that you can get it for 2 bucks on Amazon. Best $2 you'll spend!
另外,如果你想改善你的写作......关于英语,有很多令人困惑的事情。你如何掌握这些观点是一个平庸的作家与优秀作家之间的区别。要获得的最好,最小,最简洁的书(每个人都应该有副本!)被Strunk和White称为Style of Style。请注意,您可以在亚马逊上获得2美元。最好花2美元!
#1
2
I can recommend Simon Tatham's Puzzle Collection.
我可以推荐Simon Tatham的Puzzle Collection。
The comments I've read look like correct English to me. Also, they're clearly written and contain useful information about why things are done the way they are.
我读过的评论看起来对我来说是正确的英语。此外,它们写得很清楚,并包含有关为什么事情按照它们的方式完成的有用信息。
The developer documentation is also easy to read and understand, and as a side benefit you'll be reading the documentation of a system with a good and simple architecture.
开发人员文档也易于阅读和理解,作为一个附带好处,您将阅读具有良好和简单架构的系统文档。
If you aim to read something and then emulate it without explicitly understanding why doing so is a good idea, I can definitely recommend ST's puzzles. If you want an explicit understanding of what good writing is, I think ST's puzzles will serve as a good example, but you really want to read something like Strunk and White.
如果你的目的是阅读某些东西,然后在没有明确理解为什么这样做是个好主意的情况下模仿它,我绝对可以推荐ST的谜题。如果你想要明确地理解好的写作是什么,我认为ST的谜题将作为一个很好的例子,但你真的想读一些像Strunk和White这样的东西。
#2
2
I don't think comments are a good place to learn, even if you have to emulate this style. Comments are often not even correct English and good projects will not have too many comments anyway, hence, not much to learn from.
我不认为评论是一个学习的好地方,即使你必须模仿这种风格。评论往往不是正确的英语和好的项目无论如何都不会有太多的评论,因此,没有太多的东西需要学习。
If, on the other hand, you take a project that is commented extensively you can be almost sure that it's not a great role model since the programmers were incapable of conveying terse meaning. This is a generalization, of course. However, I believe it's (almost?) always true. YMMV.
另一方面,如果你采用一个被广泛评论的项目,你几乎可以肯定它不是一个伟大的榜样,因为程序员无法传达简洁的含义。当然,这是一种概括。但是,我相信它(几乎?)总是如此。因人而异。
Instead, learn English by studying the experts. There has been a question about this. I recommended “On Writing Well” by William Zinsser and I will do so again.
相反,通过研究专家来学习英语。对此存在疑问。我推荐William Zinsser写的“On Writing Well”,我将再次这样做。
(By the way, English isn't my mother tongue either.)
(顺便说一句,英语也不是我的母语。)
#3
0
I've only ever looked at small pieces of it, but I hear the linux kernel is very well commented.
我只看过它的一小部分,但我听说linux内核得到了很好的评论。
#4
#5
0
I fairly well commented open source project is Drupal . Check it at Drupal.org . I've developed several portals in it and you can actually learn quite a bit by reading comments in the modules and themes. Actually they are some times more informative then the documentation.
我相当好评论开源项目是Drupal。在Drupal.org上查看。我已经开发了几个门户网站,你可以通过阅读模块和主题中的注释来学到很多东西。实际上它们比文档更有用。
#6
0
Minix is quite well commented. They can be a bit terse in some places but the comments are very helpful.
Minix评论很好。它们在某些地方可能有点简洁,但评论非常有帮助。
#7
0
Also, if you want to improve your writing... There are a lot of confusing things about the english language. How you master these points is what distinguishes a mediocre writer from an excellent writer. The best, smallest, and most concise book to get (everyone should have a copy!) is called the Elements of Style by Strunk and White. Note that you can get it for 2 bucks on Amazon. Best $2 you'll spend!
另外,如果你想改善你的写作......关于英语,有很多令人困惑的事情。你如何掌握这些观点是一个平庸的作家与优秀作家之间的区别。要获得的最好,最小,最简洁的书(每个人都应该有副本!)被Strunk和White称为Style of Style。请注意,您可以在亚马逊上获得2美元。最好花2美元!