精华内容
下载资源
问答
  • VUE代码注释规范,代码规范
    千次阅读
    2019-08-15 10:52:09

    VUE代码注释规范,代码规范
    背景
    其实关于这一点我是深恶痛绝呀,你说我们吧eslint开了,来敲代码,就能把你的代码给规范了吧,关于组件命名和src结构都是按照VUE目录给的(项目成员已构造),功能注释和调试代码(模拟数据的部分,已注释,用于和客户方展示,判定好才可删除)和后期需求优化的地方注释。

    开发过程上到svn是不是要每日update和晚上commit来管理代码呢,当然是。可是当我把这部分注释留在svn库里就不行了,同事说我代码不规范呀,给我郁闷的。

    我就想知道你以后维护代码是要从仓库里面拉出来看的吧,你回头维护还要再想想是吧。仓库里面只能有功能注释不能有其他的注释,说是有其他的不规范,我的妈,我问你要怎么管理你这部分东西,对方提出把代码存到你的本地文件夹里面,svn里上传无注释的(仅有功能注释),我是手动狗头了,老铁。如果是这个样子,我咋开发东西呀,一口如何吃个大胖子。(注释在weabpck打包的时候会被压缩去掉的不在dist文件里面),当然我也觉得尽量少的注释会很简洁,可问题是你咋确定你的思路效果就是客户需要的呢,比如你有个颜色ui给的不好,那你要注释一下此处颜色要改吧,等需求给你了新的,你再来改的吧,不行,我的吗。有部分table你要本地看,但是没数据接口,你要上假数据吧,不行,你调试可以有但是上svn不能有,我的妈,我问你咋搞,你让我每次提交代码都要手动在电脑文件夹copy出来一份,改掉代码结构再上传?每天都要干这个事,不累呀。我有非功能注释就是为了review来慢慢完善再去掉的。哎呀,吐槽了这么多,跑题了。下面说主要的注释部分规范。

    注释规范
    总的说一下,就是注释尽量少,(显得我们专业,但维护性很差),注释要为功能性的,不能有类似待完善的说明,这种说明要自己偷偷的写出来,不放到代码里面。我看我以后还是写个说明文档,放在本地,把哪部分功能需要完善的地方(文件路径和部分代码和关键字方便定位代码区)给写在文档里面。刚好可以和SA来对接。嗯,就这么干。这比同事的专业方式(存文件夹)要强多了。
    最后得说明一点,就是最好有一个解释文件,可以是readme里面,也可以是单独文件,用来说明每一部分的功能(中文)和作者和代码修改状态,我比较推荐在readme里面写

    下面引自
    http://blog.sina.com.cn/s/blog_17689050c0102y2wp.html
    1.TEMPLATE结构内容注释
    (1)大区块之间需要回车换行,且有有单独的中文注释

    2.STYLUS注释
    (1)每个大区块的样式的需要有单独的中文注释
    (2)每个大区块样式之间需要回车换行
    (3)在STYLUS自定义函数库文件类似于mixin.styl,则需要对每个语言函数进行单独的批注,或者一些功能类似的语言函数可以根据功能分类注释

    3.SCRIPT注释
    (1)尽可能多用单行注释,注释需要与被注释的地方对齐
    (2)生命周期created()、mounted()下的所有方法调用需要单独注释,methods里面涉及接口调用的方法一定要注释,filters里面的过滤器需要注释说明功能
    命名规范:

    1.组件文件夹命名:
    (1)按照功能英文命名,过长则用 ” - ” 连接
    (2)其内部的组件名称和样式名称与文件夹同名
    (3)其风格一致
    2.静态资源文件夹static命名:
    (1)英文命名,过长则用 ” - ” 连接
    (2)其主目录需要创建一个解释文件(annotation.txt/annotation.md),在这个解释文件中使用中文批注好每个目录的内容,以及每个目录正在被哪些组件调用
    3.图片文件命名:
    (1)如果是精灵图,则需按功能命名
    (2)如果是列表渲染图片,则需要按照1-100编号命名
    (3)如果是ICON图片,则需要添加 ”icon-”前缀

    解释文件:

    1.定义:一个对当前目录下所有的文件夹的一个解释性文档,中文批注每个文件夹下的组件功能或者资源类型,如果是资源类型文件夹,则还需批注调用该文件夹的组件名称和路径
    2.名称:统一命名annotation.txt/annotation.md

    更多相关内容
  • latex添加代码注释Stop me if you’ve heard this one before… 如果您之前听过我的话,请阻止我... “Good code is self-documenting.” “的代码是自我记录。” In 20+ years of writing code for a living, ...

    latex添加代码注释

    Stop me if you’ve heard this one before…

    如果您之前听过我的话,请阻止我...

    “Good code is self-documenting.”
    “好的代码是自我记录。”

    In 20+ years of writing code for a living, this is the one phrase I’ve heard the most.

    在20多年的代码编写中,这是我最常听到的一句话。

    It’s cliché.

    这是陈词滥调。

    And like many clichés, it has a kernel of truth to it. But this truth has been so abused that most people who utter the phrase have no idea what it really means.

    像许多陈词滥调一样,它具有真实性。 但是这个真理已经被滥用了,以至于大多数说这个短语的人都不知道它的真正含义。

    Is it true? Yes.

    是真的吗 是的

    Does it mean you should never comment your code? No.

    这是否意味着您永远不要注释您的代码? 不行

    In this article we’ll look at the good, the bad, and the ugly when it comes to commenting your code.

    在本文中,我们将讨论注释代码时的好,坏和丑陋之处。

    For starters, there are really two different types of code comments. I call them documentation comments and clarification comments.

    对于初学者来说,实际上有两种不同类型的代码注释。 我称它们为文档注释澄清注释

    文档注释 (Documentation Comments)

    Documentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it. If you are building a library or framework that other developers will use, you need some form of API documentation.

    文档注释适用于可能使用您的源代码但不太可能阅读您的源代码的任何人。 如果要构建其他开发人员将使用的库或框架,则需要某种形式的API文档。

    The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it.

    您的API文档从源代码中删除的越多,随着时间的推移,它越有可能变得过时或不准确。 减轻这种情况的一种好策略是将文档直接嵌入代码中,然后使用工具将其提取。

    Here’s an example of a documentation comment from a popular JavaScript library called Lodash.

    这是来自流行JavaScript库Lodash的文档注释示例

    If you compare these comments to their online documentation, you’ll see it’s an exact match.

    如果将这些评论与他们的在线文档进行比较 ,您会发现它是完全匹配的。

    If you write documentation comments you should ensure that they follow a consistent standard and that they are easily distinguishable from any inline clarification comments you may also want to add. Some popular and well supported standards and tools include JSDoc for JavaScript, DocFx for dotNet, and JavaDoc for Java.

    如果您编写文档注释,则应确保它们遵循一致的标准,并且易于与您可能还想添加的任何在线澄清注释区分开。 一些受欢迎且受到良好支持的标准和工具包括JavaScript的JSDoc ,dotNet的DocFx和Java的JavaDoc

    The downside of these kinds of comments is that they can make your code very “noisy” and harder to read for anyone who is actively involved in maintaining it. The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code.

    这些注释的缺点是,它们会使您的代码非常“嘈杂”,而对于任何积极参与维护代码的人来说,它们都更难阅读。 好消息是,大多数代码编辑器都支持“代码折叠”,这使我们可以折叠注释,以便我们专注于代码。

    澄清评论 (Clarification comments)

    Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code.

    澄清注释适用于可能需要维护,重构或扩展您的代码的任何人(包括您将来的自己)。

    Often, a clarification comment is a code smell. It tells you that your code is too complex. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.”

    通常,澄清注释是代码的味道。 它告诉您代码太复杂。 您应该努力删除澄清注释并简化代码,因为“好的代码是自我记录的”。

    Here’s an example of a bad — though very entertaining — clarification comment.

    这是一个不好的澄清示例 ,尽管很有趣。

    /*  * Replaces with spaces  * the braces in cases  * where braces in places  * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

    Rather than decorating a slightly confusing statement with a clever rhyme — in amphibrach dimeter, no less — the author would have been far better off spending time on a function that makes the code itself easier to read and understand. Maybe a function named, removeCurlyBraces called from another function named sanitizeInput?

    与其用灵巧的韵律来修饰一个稍微令人困惑的语句( 至少用amphibrach dimeter来装饰) ,作者最好花时间在使代码本身更易于阅读和理解的函数上。 也许是从另一个名为sanitizeInput函数调用的,名为removeCurlyBraces函数?

    Don’t get me wrong, there are times — especially when you are slogging through a crushing workload — where injecting a bit of humor can be good for the soul. But when you write a funny comment to make up for bad code, it actually makes people less likely to refactor and fix the code later.

    别误会我的意思,有时候,尤其是当您在繁重的工作量中苦苦挣扎时,注入一点幽默可能对灵魂有益。 但是,当您编写有趣的注释来弥补错误的代码时,实际上会使人们不太可能在以后重构和修复代码。

    Do you really want to be the one responsible for robbing all future coders of the joy of reading that clever little rhyme? Most coders would chuckle and move on, ignoring the code smell.

    您是否真的想成为一名负责抢劫所有未来编码人员的人,以使他们阅读这种聪明的小韵律? 大多数编码人员会轻笑并继续前进,而忽略了编码的气味。

    There are also times when you come across a comment that is redundant. If the code is already simple and obvious, there’s no need to add a comment.

    有时您会遇到多余的评论。 如果代码已经很简单明了,则无需添加注释。

    Like, don’t do this nonsense:

    就像,不要胡说八道:

    /*set the value of the age integer to 32*/int age = 32;

    Still, there are times when no matter what you do to the code itself, a clarification comment is still warranted.

    尽管如此,有时无论您对代码本身做什么,仍需要澄清说明。

    Usually this happens when you need to add some context to a non-intuitive solution.

    通常,当您需要向非直观解决方案中添加一些上下文时,就会发生这种情况。

    Here’s a good example from Lodash:

    这是Lodash的一个很好的例子:

    function addSetEntry(set, value) {     /*    Don't return `set.add` because it's not chainable in IE 11.  */    set.add(value);      return set;  }

    There are also times when — after a lot of thought and experimentation — it turns out that the seemingly naive solution to a problem is actually the best. In those scenarios it is almost inevitable that some other coder will come around thinking they are much smarter than you are and start messing with the code, only to discover that your way was the best way all along.

    有时,经过大量的思考和实验,事实证明,似乎天真的解决问题的方法实际上是最好的。 在这些情况下,几乎不可避免地会有其他一些编码器出现,以为它们比您聪明得多,并开始弄乱代码,只是发现您的方式一直是最好的方式。

    Sometimes that other coder is your future self.

    有时,其他编码员是您未来的自我。

    In those cases, it’s best to save everyone the time and embarrassment and leave a comment.

    在这种情况下,最好节省每个人的时间和尴尬并发表评论。

    The following mock-comment captures this scenario perfectly:

    以下模拟注释完美地捕获了这种情况:

    /**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

    Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

    同样,以上内容是关于有趣而不是有所帮助。 但是您应该发表评论,警告其他人,如果您已经尝试并拒绝了它,则不要追求一些看似明显的“更好的解决方案”。 并且,当您这样做时,注释应指定您尝试了哪种解决方案以及为什么反对该解决方案。

    Here’s a simple example in JavaScript:

    这是JavaScript中的一个简单示例:

    /* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

    丑陋的 (The Ugly)

    So, we’ve looked at the good and the bad, but what about the ugly?

    因此,我们研究了好与坏,但是丑陋呢?

    Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

    不幸的是,在任何工作中,有时您会发现自己感到沮丧,而当您以谋生为目的编写代码时,可能很想在代码注释中消除这种沮丧。

    Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

    使用足够的代码库,您会遇到各种评论,从愤世嫉俗和沮丧到沉闷和刻薄。

    Things like the seemingly harmless

    貌似无害的事情……

    /*This code sucks, you know it and I know it.  Move on and call me an idiot later.*/

    …to the downright mean

    …… 直率的意思

    /* Class used to workaround Richard being a f***ing idiot*/

    These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

    这些事情看似很有趣,或者可能会在瞬间缓解一些挫败感,但是当他们将其纳入生产代码时,最终使编写这些代码的程序员和他们的雇主显得不专业且痛苦。

    Don't do this.

    不要这样

    If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.

    如果您喜欢这篇文章,请多次敲击掌声图标,以帮助宣传。 如果您想阅读更多类似的内容,请在下面注册我的每周开发精通通讯。

    翻译自: https://www.freecodecamp.org/news/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83/

    latex添加代码注释

    展开全文
  • Python代码注释的一些基础知识

    万次阅读 多人点赞 2019-07-16 19:11:39
    给变量、函数起合适的名字以及合理地组织代码都是很的方法。 使用注释是增加代码可读性的另一个方便简单且重要的方法! 我们将介绍编写Python注释的一些基础知识。您将学习如何优雅地编写干净、简洁的注释,以及...

    在编写Python代码时,确保您的代码易于被其他人理解是很重要的。给变量、函数起合适的名字以及合理地组织代码都是很好的方法。

    使用注释是增加代码可读性的另一个方便简单且重要的方法!

    我们将介绍编写Python注释的一些基础知识。您将学习如何优雅地编写干净、简洁的注释,以及了解何时您可能根本不需要编写任何注释。

    #为什么注释代码如此重要

    注释是任何程序的一个组成部分,它们可以以注释块的形式或者在代码行中出现,来帮助阐明解释一个复杂的函数。

    在深入研究不同类型的注释之前,让我们仔细看看为什么代码注释如此重要。

    假设在以下两种情况中,程序员不对代码进行注释。

    #当阅读你自己的代码时

    客户端A希望在最后一刻部署他们的Web服务,截止日期就快到了,所以你决定先把它整体先做好,所有“额外”的东西如文档、适当的注释等等之后再添加。

    最终,在最后期限时,及时地部署了Web服务。

    但当你还没来及进行添加注释时,你就迎来了老板要求马上开始的新项目,在进行新项目的同时,你可能会把客户A的代码注释忘得一干二净。

    六个月后,客户A需要为相同的服务构建一个补丁来满足一些新的需求。维护它是你的工作,因为你是第一个建造它的人。打开文本编辑器后……

    #“我之前到底写了什么?!”

    你花了几个小时分析你的旧代码,但你完全迷失在混乱中。您当时非常匆忙,没有正确命名变量,甚至没有在适当的控制流中设置函数。最糟糕的是,脚本中没有任何注释来告诉您什么是什么!

    开发人员总是忘记他们自己的代码所做的事情,尤其是如果代码是在很久以前编写的,或者是在很大的压力下编写的。当最后期限快到了,在电脑前几个小时导致眼睛充血时,这种压力可以用比平时更混乱的代码形式反映出来。

    一旦提交了项目,许多开发人员就会因太累了,根本无法回过头来注释他们的代码。当到了之后重新来用它的时候,可能要花上几个小时来分析自己所写的东西。

    边写代码边写注释是防止上述情况发生的一个很好的方法,请善待未来的你!

    #当别人在阅读你的代码时

    假设你是从事一个小型Django项目的唯一开发人员,感觉自己很好地理解了自己的代码,所以你不倾向于花费更多的时间来编写注释或任何其他说明文档。

    可能到年底,你的“小Django项目”已经变成了一个“20000行代码”的项目,而您的主管正在安排更多的开发人员来帮助维护它。

    新的开发人员努力工作,以迅速投入进来,但在合作的头几天,你便会意识到他们会遇到一些麻烦。在项目代码中,你使用了一些奇怪的变量名,并使用超级简洁的语法编写。这就导致新员工会花费大量的时间逐行遍历您的代码,以试图弄清楚它是如何工作的。

    在这种情况下,在代码中使用注释可以很好地帮助其他开发人员读懂你的代码,你可以通过从项目一开始就对代码进行注释来帮助与其他开发人员的合作。

    #如何用Python编写注释

    现在我们已经知道了为什么代码注释如此重要,那么让我们来看一些有关注释的基本知识,以便熟悉如何正确地使用它。

    #Python注释基础

    要用Python编写注释,只需将“#”放在您的注释内容之前:

    Python会忽略在#标记之后到行尾的所有内容,您可以在代码中的任何位置插入它们,甚至可以在代码行中使用:

    当你运行上述代码时,你只会看到This will run的输出,其他的都会被忽略。

    评论应该简短、贴切、切中要害。PEP 8建议将代码保持在79个字符或更少,代码行中的注释最多为72个字符。如果您的注释接近或超过了该长度,则需要将其转变为多行注释。

    Python多行注释

    不幸的是,Python无法像用C、Java和Go语言那样编写多行注释:

    在上述示例中,程序将忽略第一行,但其他行将引发语法错误。

    相反,像Java这样的语言可以很容易地将注释扩展到多行:

    程序会自动忽略//之间的所有内容。

    虽然Python没有这种多行注释功能,但可以在Python中创建多行注释,主要有一下两种简单的方法。

    第一种方法是在每一行后面简单地按下回车键,添加一个新的#标记,然后继续注释:

    程序将忽略以#标记开头的每一行。

    另一种方法是使用多行字符串将注释包装在一组三引号中:

    这与Java中的多行注释类似,在Java中,包含在三元引号中的所有内容都将成为注释。

    虽然这貌似提供了多行注释功能,但从技术上讲,这并不是一个注释。它仅仅是一个没有分配给任何变量的字符串,所以程序不会调用或引用它。不过,由于它在运行时会被忽略并且不会出现在字节码中,所以它可以有效地充当注释。

    但是,在放置这些多行“注释”时要小心。根据它们在程序中的位置,它们有时可以转换为docstring,这是与函数或方法相关联的文档片段。如果您在函数定义之后将这些“注释”放进去,那么想要成为注释的内容将与该对象相关联。在使用这种多行注释时要小心,如果有疑问,保险起见在后面的每一行上添加一个#标记即可。

    #Python注释快捷键

    每次需要添加注释时,都要键入#标记可能会很繁琐。那么,我们能做些什么来加快速度呢?这里有一些技巧可以帮助你更快地添加注释。

    第一就是使用多个游标,就是通过在屏幕上放置多个光标来完成任务。左键单击时,只需按住ctrl或cmd键,就会看到屏幕上闪烁的线条:

    当需要在多个地方对相同的事情进行注释时,这是最有效的。

    如果我们有很长一段文字需要注释呢?或者批量将代码转化为注释,一行一行地注释它可能需要很多时间!在这种情况下,只需选择需要作为注释的代码行并在PC上按Ctrl+/,或在Mac上按Cmd+/:

    所有选中的代码前都将加上一个#标记,并被程序忽略。

    如果注释行数较多,或者正在阅读的脚本中的注释非常长,那么您的文本编辑器可能会让您选择使用左侧的小箭头折叠它们:

    只需单击箭头以隐藏注释即可。如果长注释分散在多行,或占用程序大部分启动时间的docstring中,这种方法效果最好。

    将这些技巧结合在一起,将使您的代码注释快速、简单。

    #Python注释最佳实践

    知道如何用Python编写注释相当重要,但同样重要的是要确保注释具有可读性和易懂性。

    以下技巧,可以帮助您编写真正适合您的代码的注释。

    #为自己编写代码时

    通过正确地注释自己的代码,可以让自己的程序员生活更轻松。即使没有其他人会看到它,但你之后可能会反复看它,这是你为它添加注释的足够的理由。毕竟,您是一个开发人员,应该让您的代码容易理解。

    为自己编写注释的一个非常有用的技巧是将其作为代码的大纲。如果不确定你的程序将如何发展,那么您可以使用注释来跟踪剩余的工作,甚至可以作为跟踪高级程序流的一种方法。例如,使用注释来勾勒伪代码中的函数:

    这些注释计划出了get_top_cies,说明你准确地知道了你想要你的函数做什么,后面可以很方便地将它翻译成代码。

    使用这样的注释可以帮助你保持头脑清醒。当遍历你的程序时,将知道要获得一个功能齐全的脚本,还需要做些什么。在将注释“转换”成代码之后,请记住删除任何已经变得多余的注释,这样您的代码就可以保持清晰和干净。

    还可以使用注释作为调试过程的一部分。注释掉旧代码,看看它如何影响您的输出。如果感觉输出符合要求,那么就可以去掉程序中注释掉的代码,以提高代码的可读性。您也可以使用程序版本控制,方便后面旧代码的找回。

    最后,使用注释来定义自己代码的棘手部分。如果你放下一个项目,几个月或几年后再回到它,你将需要花费大量的时间来重新熟悉你所写的东西。为以防万一你忘记自己的代码做了什么,帮未来你一个忙,为其添加注释,这样以后就更容易更快速的重新读懂它。

    #为他人编写代码时

    人们喜欢在阅读文本信息时跳来跳去,而阅读代码也是如此。当代码出了问题您必须弄清楚到底发生了什么错误时,您才可能会逐行阅读代码。

    在大多数其他情况下,您将快速浏览变量和函数定义,以获得要点。用简单的注释解释正在发生的事情,能真正帮助开发人员了解在这个位置上做些什么。

    请善待你的同事,用注释来帮助他们浏览你的代码。如果您有一个名称不易理解的复杂方法或函数,您可能需要在def行后面添加一个简短的注释,以说明问题:

    这可以帮助正在浏览你的代码的其他开发人员了解该函数的功能。

    对于任何公共函数,我们都希望尽量包含一个关联的docstring,不管它是否复杂:

    此字符串将成为函数的.__doc__属性,并将正式与该特定方法相关联。

    PEP 257指南有多行docstring的约定。这些文档字符串出现在文件的顶部,包括对整个脚本以及它应该做什么的高级概述:

    像这样的模块级文档字符串将包含任何相关或需要知道的信息,供开发人员阅读。在编写一个函数时,建议列出所有的类、异常和函数,以及每个类的一行摘要。
    Python注释最糟实践

    正如编写Python注释有好的标准一样,有几种类型的注释要尽量避免。下面是一些例子。

    #避免:W.E.T.注释

    你的注释应该是D.R.Y,这是“Don’t Repeat Yourself.”的缩写,意味着你的代码注释应该很少或没有冗余。您不需要对一段足以解释自身的代码进行注释,如下所示:

    我们可以清楚地看到,a是返回值,因此没有必要在注释中特别地声明这一点。这就是W.E.T.注释,意思是“wrote everything twice”,也可以理解为“wasted everyone’s time”。

    W.E.T.注释可能是一个简单的错误,特别是如果在编写代码之前使用注释来规划代码。但是,一旦代码运行良好,一定要返回来删除不必要的注释。

    #避免:利用注释来弥补代码

    注释有时会反映出您的代码可能存在深层次的问题,注释是试图隐藏代码自身问题的一种方法,但注释应该支持你的代码,而不是试图弥补它。如果您的代码编写得很糟糕,那么任何注释都不会修复它。

    让我们以这个简单的例子为例:

    这段代码很不规范,在解释代码的每一行之前都有一个注释。通过为变量、函数和集合指定合理的名称,这个脚本可以变得更简单,如下所示:

    通过使用易于理解的命名方式,我们能够删除所有不必要的注释,并减少代码的长度!

    注释一般要比它们支持的代码短很多,如果你花了太多时间解释您所做的事情,那么你需要返回并重构,以使你的代码更加清晰和简洁。

    #避免:粗鲁的注释

    这是在开发团队工作时可能会出现的问题。当几个人都在处理相同的代码时,其他人可能会检查你所写的内容并进行更改。有时,你可能会遇到一个敢于写这样的评论的人:

    这种行为是极其不好的,如果不小心把这条注释留在了那里,然后一个客户看到了它,这样会很尴尬。你是一个专业人士,在你的注释中加入粗俗的话会有辱自己的身份。

    #结语

    学会优雅地使用注释是很有价值的,您不仅学习了如何将其编写得更清楚、更简洁,而且无疑你也会对Python有更深入的了解。

    知道如何用Python注释可以使所有开发人员(包括您自己)的编程生活变得更轻松!它们可以帮助其他开发人员快速了解您的代码,并帮助您重新熟悉自己的旧代码。

    注意,当使用注释尝试解释或弥补编写不良的代码时,返回并修改你的代码是更好的选择。注释以前编写的代码,无论是你自己的代码还是其他开发人员的代码,都是练习用Python编写注释的好方法。

    推荐阅读:

    零基础入门Python的最详细的源码教程

    2019年Python爬虫学习路线图完整版

    Python为何能坐稳AI人工智能的头牌语言

    Python崛起,TIOBE编程语言排行榜再创新高!

    展开全文
  • 如何优雅地使用Python中的代码注释

    千次阅读 2020-11-22 21:34:08
    数据观世界在编写Python代码时,确保您的代码易于被其他人理解是很重要的。给变量、函数起合适的名字以及合理地组织代码都是很的方法。...你还会学到:为什么代码注释如此重要用Python编写注释的最佳实践希望避...

    a50f4bfbfbedab6491b72d94fa36afc378311e98.jpg数据观世界

    在编写Python代码时,确保您的代码易于被其他人理解是很重要的。给变量、函数起合适的名字以及合理地组织代码都是很好的方法。

    使用注释是增加代码可读性的另一个方便简单且重要的方法!

    在本教程中,我们将介绍编写Python注释的一些基础知识。您将学习如何优雅地编写干净、简洁的注释,以及了解何时您可能根本不需要编写任何注释。

    你还会学到:

    为什么代码注释如此重要用Python编写注释的最佳实践希望避免的注释类型如何练习写出更清晰明了的注释为什么注释代码如此重要

    注释是任何程序的一个组成部分,它们可以以注释块的形式或者在代码行中出现,来帮助阐明解释一个复杂的函数。

    在深入研究不同类型的注释之前,让我们仔细看看为什么代码注释如此重要。

    假设在以下两种情况中,程序员不对代码进行注释。

    当阅读你自己的代码时

    客户端A希望在最后一刻部署他们的Web服务,截止日期就快到了,所以你决定先把它整体先做好,所有“额外”的东西如文档、适当的注释等等之后再添加。

    最终,在最后期限时,您及时地部署了Web服务。

    但当你还没来及进行添加注释时,你就迎来了老板要求马上开始的新项目,在进行新项目的同时,你可能会把客户A的代码注释忘得一干二净。

    六个月后,客户A需要为相同的服务构建一个补丁来满足一些新的需求。维护它是你的工作,因为你是第一个建造它的人。打开文本编辑器后……

    “我之前到底写了什么?!”

    你花了几个小时分析你的旧代码,但你完全迷失在混乱中。您当时非常匆忙,没有正确命名变量,甚至没有在适当的控制流中设置函数。最糟糕的是,脚本中没有任何注释来告诉您什么是什么!

    开发人员总是忘记他们自己的代码所做的事情,尤其是如果代码是在很久以前编写的,或者是在很大的压力下编写的。当最后期限快到了,在电脑前几个小时导致眼睛充血时,这种压力可以用比平时更混乱的代码形式反映出来。

    一旦提交了项目,许多开发人员就会因太累了,根本无法回过头来注释他们的代码。当到了之后重新来用它的时候,可能要花上几个小时来分析自己所写的东西。

    边写代码边写注释是防止上述情况发生的一个很好的方法,请善待未来的你!

    当别人在阅读你的代码时

    假设您是从事一个小型Django项目的唯一开发人员,您感觉自己很好地理解了自己的代码,所以您不倾向于花费更多的时间来编写注释或任何其他说明文档。

    可能到年底,您的“小Django项目”已经变成了一个“20000行代码”的项目,而您的主管正在安排更多的开发人员来帮助维护它。

    新的开发人员努力工作,以迅速投入进来,但在合作的头几天,你便会意识到他们会遇到一些麻烦。在项目代码中,您使用了一些奇怪的变量名,并使用超级简洁的语法编写。这就导致新员工会花费大量的时间逐行遍历您的代码,以试图弄清楚它是如何工作的。

    在这种情况下,在代码中使用注释可以很好地帮助其他开发人员读懂你的代码,您可以通过从项目一开始就对代码进行注释来帮助与其他开发人员的合作。

    如何用Python编写注释

    现在我们已经知道了为什么代码注释如此重要,那么让我们来看一些有关注释的基本知识,以便熟悉如何正确地使用它。

    Python注释基础

    要用Python编写注释,只需将“#”放在您的注释内容之前:

    u=1423805073,2256875052&fm=173&app=49&f=JPEG?w=640&h=73

    Python会忽略在#标记之后到行尾的所有内容,您可以在代码中的任何位置插入它们,甚至可以在代码行中使用:

    u=1680002328,4125179193&fm=173&app=49&f=JPEG?w=640&h=69

    当您运行上述代码时,您只会看到This will run的输出,其他的都会被忽略。

    评论应该简短、贴切、切中要害。PEP 8建议将代码保持在79个字符或更少,代码行中的注释最多为72个字符。如果您的注释接近或超过了该长度,则需要将其转变为多行注释。

    Python多行注释

    不幸的是,Python无法像用C、Java和Go语言那样编写多行注释:

    u=4132358430,2432364581&fm=173&app=49&f=JPEG?w=640&h=107&s=8152C5324B634F241055D0DA000010B3

    在上述示例中,程序将忽略第一行,但其他行将引发语法错误。

    相反,像Java这样的语言可以很容易地将注释扩展到多行:

    u=1224524288,458530522&fm=173&app=49&f=JPEG?w=640&h=108&s=85F2793349636F2418D581DA000080B3

    程序会自动忽略/*和*/之间的所有内容。

    虽然Python没有这种多行注释功能,但您可以在Python中创建多行注释,主要有以下两种简单的方法。

    第一种方法是在每一行后面简单地按下回车键,添加一个新的#标记,然后继续您的注释:

    u=2536617033,3626375634&fm=173&app=49&f=JPEG?w=640&h=130&s=8A52C51649634F244855A8D80000C0B3

    程序将忽略以#标记开头的每一行。

    另一种方法是使用多行字符串将注释包装在一组三引号中:

    u=1314125647,875159854&fm=173&app=49&f=JPEG?w=640&h=143&s=8272E53649224F244C75E9DA0000C0B3

    这与Java中的多行注释类似,在Java中,包含在三元引号中的所有内容都将成为注释。

    虽然这貌似提供了多行注释功能,但从技术上讲,这并不是一个注释。它仅仅是一个没有分配给任何变量的字符串,所以程序不会调用或引用它。不过,由于它在运行时会被忽略并且不会出现在字节码中,所以它可以有效地充当注释。

    但是,在放置这些多行“注释”时要小心。根据它们在程序中的位置,它们有时可以转换为docstring,这是与函数或方法相关联的文档片段。如果您在函数定义之后将这些“注释”放进去,那么您想要成为注释的内容将与该对象相关联。在使用这种多行注释时要小心,如果有疑问,保险起见在后面的每一行上添加一个#标记即可。

    Python注释快捷键

    每次需要添加注释时,都要键入#标记可能会很繁琐。那么,我们能做些什么来加快速度呢?这里有一些技巧可以帮助你更快地添加注释。

    第一就是使用多个游标,就是通过在屏幕上放置多个光标来完成任务。左键单击时,只需按住ctrl或cmd键,就会看到屏幕上闪烁的线条:

    u=1320111627,3497808133&fm=173&app=49&f=JPEG?w=499&h=309&s=88605D3207524C644EFDD1DA0000C0B3

    当您需要在多个地方对相同的事情进行注释时,这是最有效的。

    如果我们有很长一段文字需要注释呢?或者批量将代码转化为注释,一行一行地注释它可能需要很多时间!在这种情况下,只需选择需要作为注释的代码行并在PC上按Ctrl+/,或在Mac上按Cmd+/:

    f703738da97739121604e635f5198618367ae240.jpg

    所有选中的代码前都将加上一个#标记,并被程序忽略。

    如果您的注释行数较多,或者您正在阅读的脚本中的注释非常长,那么您的文本编辑器可能会让您选择使用左侧的小箭头折叠它们:

    b3b7d0a20cf431addb17236d4636acaf2fdd9898.jpg

    只需单击箭头以隐藏注释即可。如果长注释分散在多行,或占用程序大部分启动时间的docstring中,这种方法效果最好。

    将这些技巧结合在一起,将使您的代码注释快速、简单。

    Python注释最佳实践

    知道如何用Python编写注释相当重要,但同样重要的是要确保您的注释具有可读性和易懂性。

    以下技巧,可以帮助您编写真正适合您的代码的注释。

    为自己编写代码时

    通过正确地注释自己的代码,您可以让自己的程序员生活更轻松。即使没有其他人会看到它,但你之后可能会反复看它,这是你为它添加注释的足够的理由。毕竟,您是一个开发人员,应该让您的代码容易理解。

    为自己编写注释的一个非常有用的技巧是将其作为代码的大纲。如果您不确定您的程序将如何发展,那么您可以使用注释来跟踪剩余的工作,甚至可以作为跟踪高级程序流的一种方法。例如,使用注释来勾勒伪代码中的函数:

    u=2927250727,2842271013&fm=173&app=49&f=JPEG?w=640&h=265&s=8752C5320F624D2000E5A9DA0000C0B3

    这些注释计划出了get_top_cies(),说明你准确地知道了你想要你的函数做什么,后面可以很方便地将它翻译成代码。

    使用这样的注释可以帮助你保持头脑清醒。当您遍历您的程序时,您将知道要获得一个功能齐全的脚本,还需要做些什么。在将注释“转换”成代码之后,请记住删除任何已经变得多余的注释,这样您的代码就可以保持清晰和干净。

    还可以使用注释作为调试过程的一部分。注释掉旧代码,看看它如何影响您的输出。如果您感觉输出符合要求,那么就可以去掉程序中注释掉的代码,以提高代码的可读性。您也可以使用程序版本控制,方便后面旧代码的找回。

    最后,使用注释来定义自己代码的棘手部分。如果你放下一个项目,几个月或几年后再回到它,你将需要花费大量的时间来重新熟悉你所写的东西。为以防万一你忘记自己的代码做了什么,帮未来你一个忙,为其添加注释,这样以后就更容易更快速的重新读懂它。

    为他人编写代码时

    人们喜欢在阅读文本信息时跳来跳去,而阅读代码也是如此。当代码出了问题您必须弄清楚到底发生了什么错误时,您才可能会逐行阅读代码。

    在大多数其他情况下,您将快速浏览变量和函数定义,以获得要点。用简单的注释解释正在发生的事情,能真正帮助开发人员了解在这个位置上做些什么。

    请善待你的同事,用注释来帮助他们浏览你的代码。如果您有一个名称不易理解的复杂方法或函数,您可能需要在def行后面添加一个简短的注释,以说明问题:

    u=3584091412,778285525&fm=173&app=49&f=JPEG?w=640&h=89

    这可以帮助正在浏览您的代码的其他开发人员了解该函数的功能。

    对于任何公共函数,我们都希望尽量包含一个关联的docstring,不管它是否复杂:

    u=502399209,2938240319&fm=173&app=49&f=JPEG?w=640&h=146&s=877245324D226D201ADDC1DA0000D0B3

    此字符串将成为函数的.__doc__属性,并将正式与该特定方法相关联。

    PEP 257指南有多行docstring的约定。这些文档字符串出现在文件的顶部,包括对整个脚本以及它应该做什么的高级概述:

    u=2274636696,3066573300&fm=173&app=49&f=JPEG?w=640&h=208&s=8772E5360BE04D201E7188D00000C0B3

    像这样的模块级文档字符串将包含任何相关或需要知道的信息,供开发人员阅读。在编写一个函数时,建议列出所有的类、异常和函数,以及每个类的一行摘要。

    Python注释最糟实践

    正如编写Python注释有好的标准一样,有几种类型的注释要尽量避免。下面是一些例子。

    避免:W.E.T.注释

    你的注释应该是D.R.Y,这是“Don’t Repeat Yourself.”的缩写,意味着您的代码注释应该很少或没有冗余。您不需要对一段足以解释自身的代码进行注释,如下所示:

    u=128668574,886607111&fm=173&app=49&f=JPEG?w=640&h=73

    我们可以清楚地看到,a是返回值,因此没有必要在注释中特别地声明这一点。这就是W.E.T.注释,意思是“wrote everything twice”,也可以理解为“wasted everyone’s time”。

    W.E.T.注释可能是一个简单的错误,特别是如果在编写代码之前使用注释来规划代码。但是,一旦代码运行良好,一定要返回来删除不必要的注释。

    避免:利用注释来弥补代码

    注释有时会反映出您的代码可能存在深层次的问题,注释是试图隐藏代码自身问题的一种方法,但注释应该支持您的代码,而不是试图弥补它。如果您的代码编写得很糟糕,那么任何注释都不会修复它。

    让我们以这个简单的例子为例:

    u=842185,620697836&fm=173&app=49&f=JPEG?w=640&h=323&s=0770E1321F424D6418FD81DA0000C0B3

    这段代码很不规范,在解释代码的每一行之前都有一个注释。通过为变量、函数和集合指定合理的名称,这个脚本可以变得更简单,如下所示:

    u=2013546379,1881409141&fm=173&app=49&f=JPEG?w=640&h=249&s=8770C0320B626D20187D81DA0000C0B2

    通过使用易于理解的命名方式,我们能够删除所有不必要的注释,并减少代码的长度!

    注释一般要比它们支持的代码短很多,如果您花了太多时间解释您所做的事情,那么您需要返回并重构,以使您的代码更加清晰和简洁。

    避免:粗鲁的注释

    这是在开发团队工作时可能会出现的问题。当几个人都在处理相同的代码时,其他人可能会检查您所写的内容并进行更改。有时,你可能会遇到一个敢于写这样的评论的人:

    u=2887203662,3347706703&fm=173&app=49&f=JPEG?w=640&h=71

    这种行为是极其不好的,如果不小心把这条注释留在了那里,然后一个客户看到了它,这样会很尴尬。你是一个专业人士,在你的注释中加入粗俗的话会有辱自己的身份。

    结语

    学会优雅地使用注释是很有价值的,您不仅学习了如何将其编写得更清楚、更简洁,而且您无疑也会对Python有更深入的了解。

    知道如何用Python注释可以使所有开发人员(包括您自己)的编程生活变得更轻松!它们可以帮助其他开发人员快速了解您的代码,并帮助您重新熟悉自己的旧代码。

    注意,当您使用注释尝试解释或弥补编写不良的代码时,返回并修改您的代码是更好的选择。注释以前编写的代码,无论是您自己的代码还是其他开发人员的代码,都是练习用Python编写注释的好方法。

    展开全文
  • 码农的自我修养-对代码注释的理解

    千次阅读 2016-04-17 08:28:34
    如何写好代码注释是一个老话题,可以说一千个程序员就有一千种不同的理解。下面是从我自己工作中所看到的,所听到的,结合自己编码的体会谈一下自己的想法。对代码注释的态度大致有三种误区: 注释很重要,每一行...
  • 在酷壳,有很文章都提到了代码注释,如:《十条不错的编程观点》、《优质代码的十诫》、《整洁代码的4个提示》、《惹恼程序员的十件事》等等。今天,某国外的程序员在这里列举五种应该避免的程序注释,我觉得比较...
  • 找出这些东西一起玩得有多好(或不好)。 不工作的东西在源代码中用“NOTWORKING”注释标记,以便更容易地搜索;-) cd wc-interop grep -lr ' NOTWORKING ' src/ * 你为什么这样做,唯一的? 这是为我的 jQuery ...
  • 优秀的程序员真的不写注释吗?

    万次阅读 多人点赞 2020-05-11 07:02:23
    我在很地方看到这样一个观点,“请停止写注释,因为只有烂的代码才需要注释。”这个观点非常巧妙,它让我想起了孟子的一句话,“杨氏为我,是无君也;墨氏兼爱,是无父也。无父无君,是禽兽也。” 动不动就骂别人...
  • 整洁代码--写好注释

    2016-08-16 14:59:22
    写在标题前:看了很资料说“写注释是为了弥补代码表达意图时的失败”,的确有道理,代码确实是不太需要注释的,但这种情况目前我只感觉是存在于理想中,现实中,尤其是国内,注释还是很重要的,注释写的清楚,...
  • java尾行注释有什么不好 那天,我在有关Spring XML与注释的文章中运用了自己的原则,轻松进入了这个主题。 对于目前正在编写此新应用程序的团队来说,这种简单的输入方式也是我不使事情复杂化的方式,该应用程序的...
  • 如何写代码注释

    千次阅读 2011-12-23 16:22:10
    怎样写代码注释  以下13个小技巧可以使得你的代码在长时间内依然能够保持容易理解和维护。 1. 对不同级别的代码进行注释 对于不同级别的代码块,要使用统一的方法来进行注释。例如: 对于每一个...
  • 什么时候应该避免写代码注释

    千次阅读 2018-01-07 00:00:00
    看到标题,我知道你可能会想:“我为什么要避免代码注释,这难道不是一件好事吗?”。是的,写注释在大多数情况下是有用的。但是,请注意,我说的是“在大多数情况下”,因为有一些情况下,你不应该写注释。 还不...
  • 摘要:注释可以提高代码的可读性和可维护性,从而提高代码质量。那么什么是注释?如何写出注释?“Comment or not comment, that is the question”注释可以提高代码的可读性和可维护性,从而提高...
  • 十三个代码注释的小技巧

    千次阅读 2011-12-30 16:29:28
    1. 对不同级别的代码进行注释 对于不同级别的代码块,要使用统一的方法来进行注释。例如: 对于每一个类,需要包含一段简明扼要的描述,作者和上一次修改的时间 对于每一个方法,需要包含这个方法的用途,功能,...
  • 代码不规范,同事两行泪?

    千次阅读 多人点赞 2021-02-26 00:51:21
    最近参加了一个比赛,然后看到队友编程的代码,我觉得真的是觉得注释和命名规范的重要性了,因为几乎每个字符都要咨询他,用老师的话来说,这就是命名不规范的后续反应。所以此时的我意识到写一篇关于注...
  • 写得不好代码有各种各样的问题,会给读者带来不好的阅读体验,并且如果代码写得不够,文档和代码不一致,注释代码不一致,那么对维护人员来说,理解代码和进入项目组都是有困难的。如果代码写得不够,就...
  • 写得不好代码有各种各样的问题,会给读者带来不好的阅读体验,并且如果代码写得不够,文档和代码不一致,注释代码不一致,那么对维护人员来说,理解代码和进入项目组都是有困难的。如果代码写得不够,就需要...
  • 代码整洁 vs 代码肮脏

    万次阅读 多人点赞 2019-09-16 12:05:12
    《clean code》指出,要想写出代码,首先得知道什么是肮脏代码、什么是整洁代码;然后通过大量的刻意练习,才能真正写出整洁的代码。 WTF/min是衡量代码质量的唯一标准,Uncle Bob在书中称糟糕的代码为沼泽...
  • 本文代码实现基本按照《数据结构》课本目录顺序,外加大量的复杂算法实现,一篇文章足够。能换你一个收藏了吧?
  • 这篇文章将介绍Go的编译运行、语法规范、注释转义及API标准库知识。这系列文章入门部分将参考“尚硅谷”韩顺平老师的视频和书籍《GO高级编程》,详见参考文献,并结合作者多年的编程经验进行学习和丰富,且看且珍惜...
  • 接入百度SDK的Demo已经实现的功能有,地图显示,个人GPS定位显示,还有的就是标记地图。(后续会继续添加新的功能demo),并且,使用了Easypermission... 说实话,个人觉得百度SDK的开发文档有点不好理解的,而且还有...
  • 我的需求仅仅是注释一些API的用法,而非注释底层的实现原理。比如你首次接触mybatis,看到这狗屎的文档: 由于jar包是受保护的,不允许在源码上做写入操作,只能退而求其次: 用maven将javaDoc下载下来: ...
  • Java 注释

    千次阅读 多人点赞 2015-11-18 23:48:25
    Java 注释 五月份得知入职... 一路走来, 踩了很坑, 也有了一点小小的心得, 那就用博客的形式把他记录下来吧…  写的第一篇Java的博客, 就从最基础的Java注释开始!引 程序员圈有一个笑话 最讨厌在写代码的时
  • vscode如何添加头部注释、作者注释

    千次阅读 多人点赞 2020-10-12 20:08:07
    那么vscode如何添加头部注释,让你的代码有很明显的标识呢? 第一步: 打开Visual Studio Code编辑器。找到vscode右下角那个添加插件的按钮 点击插件按钮后, 在输入框内输入fileheader回车,选择第一个。如第二图...
  • 写得不好代码有各种各样的问题,会给读者带来不好的阅读体验,并且如果代码写得不够,文档和代码不一致,注释代码不一致,那么对维护人员来说,理解代码和进入项目组都是有困难的。如果代码写得不够,就需要...
  • 在一个成熟的团队中,CodeReview是整个研发流程中不可或缺的一步,而那些即将走向成熟的团队可能对CodeReview有很的误解和问题,也不清楚CodeReview该如何去做,本文笔者将结合自己的经验和知识,谈谈我对Code...
  • (@刘永鑫-中科院-宏基因组) eggNOG 5—蛋白功能层级注释数据库重大更新 Nucleic Acids Research[IF:11.147] ① eggNOG是一个直系同源蛋白组功能注释数据库,在基因组、宏基因组的基因功能注释方面有较应用;...
  • 今天在Eclipse写代码用到段注释代码注释一个方法,习惯使用格式化代码,结果一看格式化后的代码就乱了。就像下面那样。 觉得太乱了,而且不好对比检查。于是就想着eclipse有没有什么办法解决这个问题。一番捣鼓...
  • 代码编程规范—— 注释规范

    千次阅读 2012-08-08 17:38:56
    良好的注释规范可以为团队合作开发推波助澜,无论在项目开发,还是产品维护上都起到了至关重要的作用。应该说注释规范是一种约定,也是程序员之间良好沟通的桥梁。  我们从现在就应该养成良好的编程规范,严格...
  • 写出来了,但是过一段时间去看,ε=(´ο`)))唉这个代码为什么是这个样子的,所以说写好注释,方便你我他* 文章目录注释的作用注释的种类错误注释 注释的作用 1、代码中的一些未来可能需要的代码,这个时候我们...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 78,218
精华内容 31,287
关键字:

代码注释多好不好