专栏首页dotNET知音优秀的开发者从命名开始

优秀的开发者从命名开始

有人说,命名能力也能体现一个程序员的基本编程素养。我很赞成这句话!作为开发人员逃不过起名字这一关的,大到项目名、模块名,小到类名、方法名、参数名、参数名、变量名。而命名又对代码的质量和可读性起到很关键的决定。

如何码出高质量的代码呢?其实命名也没有那么难,关键看你重不重视,愿不愿意花时间。以下是课程笔记和阿里巴巴的开发手册中觉得适用的部分,分享出来。

课程笔记
  • 命名多长最合适?

命名的一个原则能够准确的表达其含义即可。命名可以长点也没关系。

  • 命名要可读、可搜索

这里说的可读,指的是不用用一些特别生僻的英文单词来命名。可搜索是利用开发工具的智能联想功能。比如键入获取某个对象“.Get”,IDE就会返回所有以Get开头的方法等等。例如:

  1. 获取单个对象的方法用Get做前缀
  2. 获取多个对象的方法用GetList做前缀
  3. 获取多个对象的方法用Getcount做前缀
  4. 插入的方法用 save/insert 做前缀
  5. 删除的方法用 remove/delete 做前缀
  6. 修改的方法用 update 做前缀
  • 函数多大才合适?

一个函数几百行,说明了什么?逻辑过于复杂、阅读代码的时候,很容易就会看了后面忘了前面。其实更能反映一个程序员的逻辑能力和提炼能力!要本着函数单一职责原则,进行合理的拆分!具体函数大小也没法量化,网上有一种说法,那就是不要超过一个显示屏的垂直高度。大概函数也是50行左右。

  • 注释如何写?命名很重要,注释跟命名同等重要。有人认为好的命名完全可以代替注释。个人觉得,这样的观点有点太过极端。命名再好,毕竟有长度限制,不可能足够详尽,这个时候,注释就是一个很好的补充。注释的目的是让代码更容易看懂。
阿里开发手册命名、注释部分(稍有改动)
  • 【强制】代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式也要避免采用。
  • 【强制】类名、方法名使用 UpperCamelCase 风格,但以下情形例外:DO / BO / DTO / VO / UID 等。
  • 【强制】参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格,必须遵从驼峰形式。
  • 【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。
  • 【强制】抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类命名以它要测试的类的名称开始,以 Test 结尾。
  • 【强制】杜绝完全不规范的缩写, 避免望文不知义。反例:AbstractClass“缩写” 命名成 AbsClass;condition“缩写” 命名成 condi,此类随 意缩写严重降低了代码的可阅读性。
  • 【推荐】如果模块、 接口、类、方法使用了设计模式,在命名时需体现出具体模式。说明:将设计模式体现在名字中,有利于阅读者快速理解架构设计理念。
  • 【参考】枚举类名建议带上 Enum 后缀,枚举成员名称需要全大写,单词间用下划线隔开。

说明:枚举其实就是特殊的类, 域成员均为常量, 且构造方法被默认强制是私有。

注释规约
  • 【强制】所有的抽象方法(包括接口中的方法)注释,除了返回值、参数、 异常说明外,还必须指出该方法做什么事情,实现什么功能。

说明:对子类的实现要求,或者调用注意事项,请一并说明。

  • 【强制】所有的类都必须添加创建者和创建日期。
  • 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/* */注释,注意与代码对齐。
  • 【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。
  • 【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。
  • 【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。
  • 【参考】对于注释的要求:第一、能够准确反应设计思想和代码逻辑;第二、能够描述业务含义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看的,使其能够快速接替自己的工作。
  • 【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。

最后,还有一条非常重要的,那就是,项目、团队,甚至公司,一定要制定统一的编码规范,并且通过 Code Review 督促执行,这对提高代码质量有立竿见影的效果。

本文分享自微信公众号 - dotNET知音(AAshiyou),作者:李明成

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2020-03-24

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 2020年flag,微服务架构你准备好了吗?

    权威招聘网站显示,超过五成的高薪岗位,都要求掌握微服务架构,如果还不会,你可能连初试机会都没有!想高薪?Microservice你必须懂!

    李明成
  • [一起读源码]走进C#并发队列ConcurrentQueue的内部世界

    决定从这篇文章开始,开一个读源码系列,不限制平台语言或工具,任何自己感兴趣的都会写。前几天碰到一个小问题又读了一遍ConcurrentQueue的源码,那就拿C...

    李明成
  • .NET高级特性-Emit

    在这个大数据/云计算/人工智能研发普及的时代,Python的崛起以及Javascript的前后端的侵略,程序员与企业似乎越来越青睐动态语言所带来的便捷性与高效性...

    李明成
  • 基础知识 | 每日一练(174)

    士人有百折不回之真心,才有万变不穷之妙用。立业建功,事事要从实地着脚,若少慕声闻,便成伪果;讲道修德,念念要从虚处立基,若稍计功效,便落尘情。 ...

    闫小林
  • Vim实现批量注释的方法

    调试代码的时候,免不了要批量注释/取消代码注释,很多IDE都有快捷键将你选中的…

    白凡
  • 客户让你给代码加注释怎么办?

    作为乙方,我以前听过一些同事说客户要求给代码加注释,一开始自己不以为然,直到有一天这件事情发生在我身上:某大有可为的项目接近尾声,准备下项目前一周,PM说接到客...

    袁慎建@ThoughtWorks
  • 代码洁癖系列(四):可忽略的注释

    刚开始学编程的时候,老师就告诉我们,注释很重要,但是一直到现在,也没有人真正告诉过我要怎么写注释。还有很多人甚至干脆不写注释。所以今天想聊一下到底如何写注释。

    Jackeyzhe
  • 如何避免自己写的代码成为别人眼中的一坨屎!

    摘要: Any fool can write code that a computer can understand. Good programmers wri...

    Java后端技术
  • C++注释风格建议

    有个笑话,一位从不写注释的程序员在编写一段复杂的代码时,骄傲地认为这段代码只有自己和上帝知道它是干嘛的,等过了一段时间再回顾时,发现没有注释,感叹到这段代码现在...

    Dabelv
  • Java-初级编码规范

    良好的编码规范和习惯会让你的代码锦上添花,同时也会大大的增加团队协作开发的效率,避免很多细节的问题,从而大大的提高你的代码的可阅读性,同时也是一个优秀开发者的必...

    老九学堂-小师弟

扫码关注云+社区

领取腾讯云代金券