编写可读代码的艺术chapter 1-6

最新推荐文章于 2024-05-29 17:45:44 发布

WhateverYoung

最新推荐文章于 2024-05-29 17:45:44 发布

阅读量394

点赞数

CC 4.0 BY-SA版权

分类专栏： Code Standard 文章标签：注释代码可读性

本文链接：https://blog.youkuaiyun.com/yangfeng2014/article/details/50598869

Code Standard 专栏收录该内容

3 篇文章

订阅专栏

本文详细阐述了提升代码可读性的核心原则，包括命名规范、注释策略以及风格一致性，旨在帮助开发者构建易于理解、维护的代码库。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

表面层次的改进

1. 总章

可读性基本定理：代码应当易于理解，代码的写法应当使别人理解它的时间最小化。

2. 命名

1. 词汇表达含义尽可能的准确

int  size();
//size没有承载信息，应当根据实际情况求改为诸如：Height，NumNodes，MemoryBytes...
void stop();
//stop同样，可以考虑的词有pause，kill，resume...

2 . 选择更有表现力的单词

单词	更多选择
send	deliver dispatch announce distribute route
find	search extract locate recover
start	launch create begin open
make	create set up build generate compose add new

//尽量避免temp等名字，只用在那些短期存在且临时性的变量中
//为名字附带更多的信息
//但单位的变量可以避免很多错误
double start_ms;
double end_s;
//附带重要属性
html_utf8
//在小的作用域内使用短的名字
//不要使用字母缩写
//删除无用词汇
ConvertToString -> ToString
//类内成员命名，用一个统一的规法
int offste_;
int p_offset;

3 .选择表达范围的词汇

(min, max)
[first, last]
[start\begin, end)

3. 审美

使用一致的布局，让读者很快就习惯这种风格
让相似的代码看上去相似
把相关的代码行分组，形成代码块
留白、对齐、代码块、文法
一致的风格优于“正确”的风格

4. 注释

注释的关键思想是：注释的目的是尽可能的帮助读者了解的信息和作者一样多。

1. 什么不需要注释

不要为那些从代码本身就能快速推断的事实写注释
不要为了注释而注释
不给不好的名字加注释，先修改名字
好代码 > 坏代码 + 好注释

int lonsl;
//find the node in the given subtree, with the given name,using the given depth
Node * FindNodeInSubTree(Node* subtree, string name, int depth);

//Find a node with the given 'name' or return NULL
//If depth <= 0, only 'subtree' is inspected
//If depth == N, only 'subtree' and N levels below are inspected
Node * FindNodeInSubTree(Node* subtree, string name, int depth);

2. 什么需要注释

记录你的思想

//出乎意料的是，对于这些数据使用二叉树比用哈希表块40%
//作为整体可能会丢掉一些词，但是这没问题，要100%解决太困难了
//这个类正变得混乱，应该建立一个'name'子类来重构了
//TODO: 采用更快的算法
//HACK:对一个问题不得不采取粗糙的解决方案
//XXX:危险！这里有重要的问题
//给常量加注释，但是名字已经足够清楚不用
// as long as it is >= 2 * num_processors, that's good enough
const int NUM_THREADS = 8;