ASPIRE

[collect]开源项目编程风格指南

==Google 开源项目风格指南 (中文版)==
声明：

本项目并非 Google 官方项目，而是由国内程序员凭热情创建和维护。

如果你关注的是 Google 官方英文版，请移步 Google Style Guide

每个较大的开源项目都有自己的风格指南：关于如何为该项目编写代码的一系列约定 (有时候会比较武断)。当所有代码均保持一致的风格，在理解大型代码库时更为轻松。

“风格” 的含义涵盖范围广，从 “变量使用驼峰格式 (camelCase)” 到 “决不使用全局变量” 再到 “决不使用异常”。英文版项目维护的是在 Google 使用的编程风格指南。如果你正在修改的项目源自 Google，你可能会被引导至英文版项目页面，以了解项目所使用的风格。

我们已经发布了四份 中文版 的风格指南：

  1. Google C++ 风格指南
  2. Google Objective-C 风格指南
  3. Google Python 风格指南
  4. Google JSON 风格指南

中文版项目采用 reStructuredText 纯文本标记语法，并使用 Sphinx 生成 HTML / CHM / PDF 等文档格式。

英文版项目还包含 cpplint —— 一个用来帮助适应风格准则的工具，以及 google-c-style.el，Google 风格的 Emacs 配置文件。

另外，招募自愿者翻译 JavaScript Style Guide 以及 XML Document Format Style Guide，有意者请联系 brantyoung。

原文链接：

http://zh-google-styleguide.readthedocs.org/en/latest/

==

除了以上Google家的编程风格指南，国内的厂商华为也有几份不错的指南/规范可以参考学习：

=EOF=

admin

,
,

《 “[collect]开源项目编程风格指南” 》 有 27 条评论

  7. 代码质量管控的四个阶段
    https://zhuanlan.zhihu.com/p/29086959
    `
    代码质量管控通常需要经历的四个阶段：
    规范化 – 建立代码规范与Code Review制度
    自动化 – 使用工具自动检查代码质量
    流程化 – 将代码质量检查与代码流动过程绑定
    中心化 – 以团队整体为视角，集中管理代码规范，并实现质量状况透明化
    `

    回复

  12. 如何提高代码质量？
    https://mp.weixin.qq.com/s/nyqbRLFEofONb0mevyoYow
    `
    对靠谱程序员来说，代码质量，以及一颗能够洞悉高质量软件编写之道的大脑弥足珍贵。

    本文从 产品，接口，指标，日志，代码清晰度，代码复杂度 等方面，谈谈如何提高代码质量。

    好的产品经理未必是个好的程序员，但好的程序员一定是个好的产品经理。

    产品经理的工作是什么？是把复杂的逻辑用清晰的，易用的方式（接口）展现给用户。

    程序员的产品是代码，代码的用户是其它程序员 —— 所以高质量的代码是让别的程序员容易理解，容易使用的代码。注意，这个层次的容易理解，是指结构，原理和接口上容易理解，而并非代码的细节容易理解。
    `

    回复

  13. 3种常见的代码规范类型
    https://mp.weixin.qq.com/s/vYevkReh6cCgc5aV2XTJ5g
    `
    所以在技术上稍有追求的团队都会意识到规范的重要性。

    什么样的代码才是好代码？
    曾经看到有位作者说“风格一致”的代码就是好代码，即团队所有人写出来的代码就像是一个人所写的。这个观点我非常赞同。

    没有一劳永逸的工具或方法：
    使用静态校验工具来规范代码的基本书写规范；
    然后对于校验工具无法完成的规范写成文档；
    最后通过代码合并时的代码审查进行保障。
    `

    回复

  15. 是否要做Code Review？与BAT资深架构师争论之后的思考
    https://mp.weixin.qq.com/s/XANbbq9jDTMKytA-Jy7N1w
    `
    1. Code Review的意义有多大？
    1）三人行必有我师
    2）高手之间的过招在细节
    3）Code Review是摒弃个人英雄主义的作坊式开发模式的有效手段
    4）Code Review过程是对代码可读性的考察
    5）Code Review可以提高代码质量
    6）Code Review过程是一种mentor（传帮带）的有效途径
    7）Code Review保证不止一人对代码熟悉
    8）Code Review可以打造良好的技术氛围
    9）Code Review是一种沟通方式
    10）Review提高大家自律性

    2. Code Review反对声音有哪些？
    1）有人认为Code Review流程太长，太浪费时间，特别是业务逼，工期紧的时候，今天改的代码，明天就要上，如果等同事Review，同事还有可能没时间。
    2）有人认为有了黑盒测试，写的代码给测试团队测试就ok了，Code Review没有必要，ROI（投入产出比）不高。
    3）有人认为业务一直在变，今天写的明天可能就改，代码有可能不会维护很久，代码写得太好也没用。

    3. Code Review如何落地执行？
    1）团队成员水平比较低，不知道Review什么，也Review不出什么。自己代码都没写明白，不知道什么是好的代码，什么是差的，更不要说告诉别人了，大眼瞪小眼，只能Review点语法的了。
    2）还有一种情况是，开始的时候大家Code Review都还挺认真，但是时间长了，大家觉得这事跟KPI无关，而且我还要看别人的代码，理解业务，多浪费我时间啊。慢慢地就会发生这样的情况：有人提交了代码，随便抓个人Review，Review的人也不认真，随便扫一眼就点approve了。一旦发生破窗效应，Code Review也就会变成流于形式了。
    `

    回复

  18. 微软是如何做 Code Review 的
    https://juejin.im/post/5db7c542518825644e28b423
    https://www.michaelagreiler.com/code-reviews-at-microsoft-how-to-code-review-at-a-large-software-company/
    `
    Microsoft 的代码审查是开发过程中不可或缺的一部分
    关于 Microsoft 代码审查的一个调查
    您可以从 Microsoft 的代码审查实践中学到什么？
    Microsoft 工程师多久做一次代码审查？
    代码审查有哪些好处？
    开发人员通常如何进行代码审查？
    Microsoft 的代码审查通常是通过内部工具完成的
    Rose 如何在 Microsoft 进行代码审查？
    Rose 如何选择合适的代码审阅者？
    谁是相关的审阅者？
    Rose 要求审阅者提供反馈
    接收反馈是一个反复的过程
    Rose 准备了代码的新版本
    所有审阅者都批准，Rose 签入代码
    并非所有团队都一样
    包含测试结果的代码审查
    包含用户界面的代码审查
    包括静态分析的代码审查
    Microsoft 的代码审查工具
    CodeFlow 的界面说明
    注释功能
    评论功能
    代码审查修订之间的比较
    代码审查分析工具
    Micorsoft 代码审查的未来
    `

    回复

  19. Code Review最佳实践
    https://www.cnblogs.com/dotey/p/11216430.html
    `
    # Code Review有什么好处？
    首先是团队知识共享的角度
    然后是代码质量的角度
    还有团队规范的角度

    # 该怎么做？
    把Code Review作为开发流程的必选项而不是可选项
    把Code Review变成一种开发文化而不仅仅是一种制度

    # 一些Code Review的经验技巧
    选什么工具辅助做CODE REVIEW？
    配合什么样的开发流程比较好？
    真遇到紧急情况，来不及代码审查怎么办？
    先设计再编码
    代码在提交CODE REVIEW之前，作者要自己先REVIEW和测试一遍
    PR要小
    对评论进行分级
    评论要友好，避免负面词汇；有说不清楚的问题当面沟通
    `

    回复

  20. Things That You Can Do to Improve Code Quality
    https://medium.com/better-programming/things-that-you-can-do-to-improve-code-quality-c746c30e7521
    `
    1. Four-Eyes Principle
    2. Continuous Integration
    3. Coding Conventions
    4. Test, Test, Test
    5. Analyze Bugs
    6. Start Measuring
    * Defect metric
    * Complexity metrics
    `

    【译】做好这几件事，代码质量可以提升一个档次
    https://www.cnblogs.com/Jackeyzhe/p/11768273.html
    `
    1. 代码审查(code review)
    2. 持续集成
    3. 编码规范
    4. 测试，测试，测试
    5. 分析缺陷
    6. 开始量化
    * 缺陷指标
    * 复杂度指标
    `

    回复

  21. Code Review 失败后总结的几个实践技巧
    https://xie.infoq.cn/article/ecb047ec7025e82383010067b
    `
    资深的程序员都知道 Code Review 可以对代码质量，代码规范，团队代码能力提升带来很大的提升，还有著名的技术专家“左耳朵耗子”也说过：
    
    我认为没有 Code Review 的公司都没有必要呆（因为不做 Code Review 的公司一定是不尊重技术的）
    – 出自《程序员的练级攻略 – 修养篇》
    
    国外很多技术公司都非常重视 Code Review 也都做的特别好，例如 Google，亚马逊，但是国内很多公司在践行 Code Review 的时候却是步履蹒跚，步步艰难，选用的方法不对，最终导致事倍功半的结果，总结一下我见过的几种情况：
    
    * 因为 Code Review 导致团队成员之间相互指责，团队凝聚力产生间隙
    * Code Review 形式化，没有提升代码质量，减少 bug，反而降低开发效率
    * Code Review 确实产生了效果，但是因为流程太重，导致团队效率降低
    
    我们也在践行 Code Review，探索的路上也遇到一些障碍和经验，总结分享一下，如果你也遇到这些问题，或许可以花一点时间读一读这篇文章，说不定会有帮助。
    
    Code Review 能带来哪些好处，本文就不说了，大家都很熟悉了，本文主要简单说一下 Code Review 有哪几个基本的共识和原则：
    
    * Code Review 高效的原则是用机器去做大部分的事情
    * Code Review 的时机（天时地利人和）
    * 推行 Code Review 的关键原则
    `

    Code Review最佳实践
    https://www.cnblogs.com/dotey/p/11216430.html

    我们是怎么做Code Review的
    https://www.cnblogs.com/wenhx/p/How-We-Code-Review.html

    大家的公司的 Code Review 都是怎么做的？遇到过哪些问题？
    https://www.zhihu.com/question/41089988

    回复

  22. 面向DevSecOps的编码安全指南 —— JavaScript篇
    https://security.tencent.com/index.php/blog/msg/172
    `
    I. 背景

    近年来，无论是DevSecOps，还是Google SRE的可靠和安全性理念，都提倡“安全需要每个工程师的参与”。其中涉及的“安全左移”理念也再次被推向前台，获得关注。

    除安全团队建设一系列安全机制和工具外，每位开发者也可以身体力行地参与进来 —— 编写安全的代码，从源头杜绝漏洞。这时，就需要一份详实的参考材料和行动大纲。

    几位对研发安全感兴趣的一线研究员，首次尝试从开发者视角，分功能、语言梳理了编码的最佳安全实践。包括C++、Go、JavaScript等。TSRC博客将分语言逐批与业界分享。

    1.1 指南是如何梳理、编写的？

    1.1.1 聚合各语言、组件、框架文档中的最佳安全实践

    各语言、开发框架的文档中，一般也会给出安全加固指引。但相对分散，容易遗忘。通过代码安全指南的整合，能强化开发者们的安全意识。

    1.1.2 参考业界经验，开展原创

    在参考调研CWE、OWASP等现有规范的基础上，我们还注意到：在日常研发过程中，由于开发者首要考虑的是如何实现功能来完成需求。通过阐述安全的函数使用方式，更方便开发者记忆。

    因此，采用了一种新的编排和阐述方式。尽管内容分类及表述方式有别，但核心内容殊途同归。

    1.1.3 基于内外部已知的漏洞案例的复盘、抽象，不断完善指引条目

    借助对内、外已知的漏洞案例的复盘，提炼产生漏洞的编码模式，不断补充先前未考虑到的风险规避建议。

    1.1.4 举一反三，推导鲜有提及的风险点，力求面面俱到

    除参考业界经验、沉淀转化已知漏洞案例外，我们还“主动出击”。结合各类开发文档和提炼的漏洞产生原因，挖掘鲜有提及的风险点加入《指南》中。以jQuery的.html()错误使用为例，漏洞原理是，传入.html()的变量值包含未过滤的HTML标签内容，产生DOM XSS。

    1.2 应用与落地

    编码安全指南不仅可作为一线开发者的权威参考，还有助于开发黑、白盒漏洞扫描工具/策略。但设立指南只是安全建设“千里之行”的第一步，我们还在探索静态源代码分析、框架安全功能建设、安全开发库、自动漏洞修复等机制配合，进一步推动安全建设，欢迎关注TSRC的后续分享。
    `

    回复

  23. 写代码注释的最佳实践(Best practices for writing code comments)
    https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/
    `
    While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it’s easy to measure the quantity of comments in a program, it’s hard to measure the quality, and the two are not necessarily correlated. A bad comment is worse than no comment at all. Here are some rules to help you achieve a happy medium.

    Rule 1: Comments should not duplicate the code.

    Rule 2: Good comments do not excuse unclear code.

    Rule 3: If you can’t write a clear comment, there may be a problem with the code.

    Rule 4: Comments should dispel confusion, not cause it.

    Rule 5: Explain unidiomatic code in comments.

    Rule 6: Provide links to the original source of copied code.

    Rule 7: Include links to external references where they will be most helpful.

    Rule 8: Add comments when fixing bugs.

    Rule 9: Use comments to mark incomplete implementations.
    ==

    规则1:注释不应该只是代码的重复。

    规则2:代码不好不是注释不好的借口。

    规则3:如果你不能把注释写清楚，可能是代码有问题。

    规则4:注释应该消除歧义，而不是造成歧义。

    规则5:在注释中要对不符合语言习惯的代码进行解释说明。

    规则6:提供复制代码的原始来源链接。

    规则7:当外部资源/引用有帮助时要记得带上链接。

    规则8:在修复bug时添加注释。

    规则9:使用注释来标记不完整的实现。
    `

    回复

  24. 代码安全指南
    `
    面向开发人员梳理的代码安全指南，旨在梳理API层面的风险点并提供详实可行的安全编码方案。

    理念
    基于DevSecOps理念，我们希望用开发者更易懂的方式阐述安全编码方案，引导从源头规避漏洞。

    代码安全指引可用于以下场景：
    * 开发人员日常参考
    * 编写安全系统扫描策略
    * 安全组件开发
    * 漏洞修复指引

    规范 最后修订日期
    C/C++安全指南 2021-05-18
    JavaScript安全指南 2021-05-18
    Node安全指南 2021-05-18
    Go安全指南 2021-05-18
    Java安全指南 2021-05-18
    Python安全指南 2021-05-18
    `
    https://github.com/Tencent/secguide

    回复

  25. Java安全编码规范-1.0.4 by k4n5ha0
    https://gitee.com/9199771/sec_coding/blob/master/sec_coding.md
    `
    编写依据与参考文件：
    1.《信息安全技术 应用软件安全编程指南》（国标 GBT38674-2020）
    2.《Common Weakness Enumeration》 – 国际通用计算机软件缺陷字典
    3.《OWASP Top 10 2017》 – 2017年十大Web 应用程序安全风险
    4.《fortify – 代码审计规则》
    5.《java开发手册》（阿里巴巴出品）
    `

    回复

  26. 谷歌工程最佳实践
    https://mp.weixin.qq.com/s/ZjjT6BtTqzXaAZWrxPLxcw
    `
    最近公司同事作了个Code Review的分享，于是乎我系统学习了下《谷歌工程实践》，里面主要讲的是Code Review。写下本文作为笔记。
    * 前言
    * 术语
    * 代码审查者指南
    __ * Code Review 标准
    __ * Code Review 要点
    __ * 查看CL的步骤
    __ * Code Review 速度
    __ * 如何撰写 Code Review 评论
    __ * 处理 Code Review 中的拖延
    * 代码开发者指南
    __ * 写好 CL 描述
    __ * 小型 CL
    __ * 如何处理审查者的评论
    * 总结
    __ * 代码审查者视角
    __ * 代码开发者视角

    代码审查者视角
    * 以制定审核标准为前提，尽可能快速、及时的反馈代码开发者的合并请求。
    * 对于评论要保持友善、提供引导，以最终代码质量、公司价值为导向。
    * 做好沟通，有疑问及时沟通、接受解释。

    代码开发者视角
    * 写好CL的描述。
    * 提供小的CL、相关测试代码不分离、重构代码分离、不破坏构建。
    * 以代码质量、公司价值为结果导向，及时修复、做好沟通。
    `
    参考资料
    [1]《谷歌工程实践》: https://jimmysong.io/eng-practices/
    [2]《Google Engineering Practices Documentation 》: https://github.com/google/eng-practices
    [3]Git 团队协作常用术语: https://blog.csdn.net/qq_15988951/article/details/108331701
    [4]LGTM : code review 行话: “https://blog.csdn.net/weixin_41287260/article/details/108676433”
    [5]《Google Style Guides》: https://google.github.io/styleguide/

    回复

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注