唯品秀博客
首页 > 别具匠心 > 【YQN】源码文件规范 (草稿)

【YQN】源码文件规范 (草稿)

2017年04月23日 唯品秀 1359次浏览

1 引言

  • 该文档主要的设计目标是让项目的源码文件的风格保持一致,使源码文件方便格式化与管理。
  • 2 文件命名

  • 使用 `all-lowercase-with-dashes命名方式。文件名建议只使用小写字母,不使用大写字母;文件名包含多个单词时,单词之间建议使用半角的连词线(-)分隔。
  • 为了醒目,某些说明文件的文件名,可以使用大写字母,比如README、LICENSE。
  • 扩展阅读 all-lowercase-with-dashes
  • 3 文件注释

    3.1 开源项目
  • 文件头只要添加文件描述,不需要添加作者信息和版权信息,author 和 contributors 信息,在 GitHub 上可以清晰看出来。
  • 1
    2
    3
    /**
     * 文件描述
     */
    3.2 业务项目
  • 添加文件描述
  • 使用 @copyright 标识,添加版权信息。(公司内部项目则无需版权信息)
  • 使用 @author 标识,添加上责任人信息,以便遇到问题时,快速找到相关责任人。
  • 通常情况文件在被创建时标识的是创建者。

    随着项目的进展,模块移交给其他人,新的责任人在新增代码时,添加 @author 标识应该把自己的名字添加在创建人的前面。

    @author 标识具有多人时,按照责任进行排序。也就是如果有问题,就是找第一个人应该比找第二个人有效。

    @author 中的名字不允许被删除。任何劳动成果都应该被尊重。

  • 使用 @since 标识,描述此功能何时被添加进来的,可以为版本号,也可以为创建时间。
  • 1
    2
    3
    4
    5
    6
    /**
     * 文件描述
     * @copyright Copyright ${COMPNAY} All Rights Reserved.
     * @author ${USER}
     * @since ${DATE}
     */

    4 编辑器配置

  • 官网链接:http://editorconfig.org
  • 配置选项:https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties
  • 文件编码
  • charset = utf-8
  • 说明: 使用无 BOM 的 UTF-8 编码,UTF-8 编码具有更广泛的适应性,BOM 在使用程序或工具处理文件时可能造成不必要的干扰。
  • 缩进类型
  • indent_style = space
  • 说明: 使用空格缩进,将制表符转为 2 个空格;因为使用制表符容易出现空格和制表符混用,而且不同的编辑器制表符的长度可能不一致,在不同的地方查看容易出现排版错乱。
  • 缩进数量
  • indent_size = 4
  • 说明: 一般设置 2 个或 4 个空格,项目内保持统一,不混用。为了不让缩进占用了太多的列宽,建议使用 2 个空格作为缩进。
  • 换行符
  • end_of_line = lf
  • 说明: 换行符格式,详细介绍请查看Wiki:换行。
  • 行末空格
  • trim_trailing_whitespace = true
  • 说明: 自动清除所有行末空格
  • 结尾空行
  • insert_final_newline = true
  • 说明: 文件尾保留一个空行。UNIX 对文本文件的定义是由多行组成,每行需以换行符结尾,文件是流式的,文件尾保留一个空行可以被任意的拼接并且拼接后仍然保证完整性。
  • 单行列宽
  • max_line_length = 80
  • 说明: 尽量让你的代码保持在 80 列之内。终端界面默认显示都是 80 列宽。80 列限制事实上有助于避免代码可读性失控, 比如超多重嵌套块, 超多重函数调用等等。在语句的行长度超过 120 时,根据逻辑条件合理缩进。
  • 5 .editorconfig 配置示例

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # http://editorconfig.org

    root = true

    [*]
    charset = utf-8
    end_of_line = lf
    indent_style = space
    indent_size = 4
    trim_trailing_whitespace = true
    max_line_length = 80
    insert_final_newline = true

    [{package.json,.**}]
    indent_style = space
    indent_size = 2

    「两年博客,如果觉得我的文章对您有用,请帮助本站成长」

    赞( 0 ) 打赏

    谢谢你请我吃鸡腿*^_^*

    支付宝
    微信
    0

    谢谢你请我吃鸡腿*^_^*

    支付宝
    微信
    标签:

    上一篇:

    下一篇:

    共有 0 条评论 - 【YQN】源码文件规范 (草稿)

    博客简介

    唯品秀博客: weipxiu.com,一个关注Web前端开发技术、关注用户体验、坚持更多原创实战教程的个人网站,愿景:成为宇宙中最具有代表性的前端博客,期待您的参与 

    精彩评论

    友情链接

    他们同样是一群网虫,却不是每天泡在网上游走在淘宝和网游之间、刷着本来就快要透支的信用卡。他们或许没有踏出国门一步,但同学却不局限在一国一校,而是遍及全球!

    站点统计

    • 文章总数: 190 篇
    • 草稿数目: 2 篇
    • 分类数目: 13 个
    • 页面总数: 21 个
    • 评论总数: 878 条
    • 链接总数: 13 个
    • 标签总数: 371 个
    • 建站时间: 886 天
    • 注册用户: 690 人
    • 访问总量: 8673534 次
    • 最近更新: 2019年5月17日
    服务热线:
     173xxxx7240

     QQ在线交流

     旺旺在线