API设计原则 – Qt官网的设计实践总结

2017年07月25日李鼎评论 26 条评论 87,132 人阅读

（感谢好友 @李鼎翻译此文）

原文链接：API Design Principles – Qt Wiki
基于Gary的影响力上 Gary Gao 的译文稿：C++的API设计指导

译序

Qt的设计水准在业界很有口碑，一致、易于掌握和强大的API是Qt最著名的优点之一。此文既是Qt官网上的API设计指导准则，也是Qt在API设计上的实践总结。虽然Qt用的是C++，但其中设计原则和思考是具有普适性的（如果你对C++还不精通，可以忽略与C++强相关或是过于细节的部分，仍然可以学习或梳理关于API设计最有价值的内容）。整个篇幅中有很多示例，是关于API设计一篇难得的好文章。

需要注意的是，这篇Wiki有一些内容并不完整，所以，可能会有一些阅读上的问题，我们对此做了一些相关的注释。

PS：翻译中肯定会有不足和不对之处，欢迎评论&交流；另译文源码在GitHub的这个仓库中，可以提交Issue/Fork后提交代码来建议/指正。

API设计原则

一致、易于掌握和强大的API是Qt最著名的优点之一。此文总结了我们在设计Qt风格API的过程中所积累的诀窍（know-how）。其中许多是通用准则；而其他的则更偏向于约定，遵循这些约定主要是为了与已有的API保持一致。

虽然这些准则主要用于对外的API（public API），但在设计对内的API（private API）时也推荐遵循相同的技巧（techniques），作为开发者之间协作的礼仪（courtesy）。

…

阅读全文 Read More

(48 人打了分，平均分： 3.48 )

Linus：利用二级指针删除单向链表

2013年02月04日 Leo 评论 195 条评论 138,687 人阅读

感谢网友full_of_bull投递此文（注：此文最初发表在这个这里，我对原文后半段修改了许多，并加入了插图）

Linus大婶在slashdot上回答一些编程爱好者的提问，其中一个人问他什么样的代码是他所喜好的，大婶表述了自己一些观点之后，举了一个指针的例子，解释了什么才是core low-level coding。

下面是Linus的教学原文及翻译——

“At the opposite end of the spectrum, I actually wish more people understood the really core low-level kind of coding. Not big, complex stuff like the lockless name lookup, but simply good use of pointers-to-pointers etc. For example, I’ve seen too many people who delete a singly-linked list entry by keeping track of the “prev” entry, and then to delete the entry, doing something like。（在这段话的最后，我实际上希望更多的人了解什么是真正的核心底层代码。这并不像无锁文件名查询（注：可能是git源码里的设计）那样庞大、复杂，只是仅仅像诸如使用二级指针那样简单的技术。例如，我见过很多人在删除一个单项链表的时候，维护了一个”prev”表项指针，然后删除当前表项，就像这样）”

if (prev)
    prev->next = entry->next;
else
    list_head = entry->next;

and whenever I see code like that, I just go “This person doesn’t understand pointers”. And it’s sadly quite common.（当我看到这样的代码时，我就会想“这个人不了解指针”。令人难过的是这太常见了。）

…

阅读全文 Read More

(57 人打了分，平均分： 4.25 )

如此理解面向对象编程

2012年12月13日陈皓评论 185 条评论 182,517 人阅读

从Rob Pike 的 Google+上的一个推看到了一篇叫《Understanding Object Oriented Programming》的文章，我先把这篇文章简述一下，然后再说说老牌黑客Rob Pike的评论。

先看这篇教程是怎么来讲述OOP的。它先给了下面这个问题，这个问题需要输出一段关于操作系统的文字：假设Unix很不错，Windows很差。

这个把下面这段代码描述成是Hacker Solution。（这帮人觉得下面这叫黑客？我估计这帮人真是没看过C语言的代码）

public class PrintOS
{
	public static void main(final String[] args)
	{
		String osName = System.getProperty("os.name") ;
		if (osName.equals("SunOS") || osName.equals("Linux"))
		{
			System.out.println("This is a UNIX box and therefore good.") ;
		}
		else if (osName.equals("Windows NT") || osName.equals("Windows 95"))
		{
			System.out.println("This is a Windows box and therefore bad.") ;
		}
		else
		{
			System.out.println("This is not a box.") ;
		}
	}
}

然后开始用面向对象的编程方式一步一步地进化这个代码。

先是以过程化的思路来重构之。

…

阅读全文 Read More

(63 人打了分，平均分： 4.25 )

代码执行的效率

2012年07月13日陈皓评论 70 条评论 58,193 人阅读

在《性能调优攻略》里，我说过，要调优性需要找到程序中的Hotspot，也就是被调用最多的地方，这种地方，只要你能优化一点点，你的性能就会有质的提高。在这里我给大家举三个关于代码执行效率的例子（它们都来自于网上）

第一个例子

PHP中Getter和Setter的效率（来源reddit）

这个例子比较简单，你可以跳过。

考虑下面的PHP代码：我们可看到，使用Getter/Setter的方式，性能要比直接读写成员变量要差一倍以上。

<?php
	//dog_naive.php

	class dog {
		public $name = "";
		public function setName($name) {
			$this-&gt;name = $name;
		}
		public function getName() {
			return $this-&gt;name;
		}
	}

	$rover = new dog();
        //通过Getter/Setter方式
	for ($x=0; $x<10; $x++) {
		$t = microtime(true);
		for ($i=0; $i<1000000; $i++) {
			$rover->setName("rover");
			$n = $rover->getName();
		}
		echo microtime(true) - $t;
		echo "\n";
	}
        //直接存取变量方式
        for ($x=0; $x<10; $x++) {
		$t = microtime(true);
		for($i=0; $i<1000000; $i++) {
			$rover->name = "rover";
			$n = $rover->name;
		}
		echo microtime(true) - $t;
		echo "\n";
	}
?>

这个并没有什么稀，因为有函数调用的开销，函数调用需要压栈出栈，需要传值，有时还要需要中断，要干的事太多了。所以，代码多了，效率自然就慢了。所有的语言都这个德行，这就是为什么C++要引入inline的原因。而且Java在打开优化的时候也可以优化之。但是对于动态语言来说，这个事就变得有点困难了。

…

阅读全文 Read More

(18 人打了分，平均分： 3.72 )

千万不要把 bool 设计成函数参数

2011年09月08日陈皓评论 94 条评论 72,399 人阅读

我们有很多Coding Style 或代码规范。但这一条可能会经常被我们所遗忘，就是我们经常会在函数的参数里使用bool参数，这会大大地降低代码的可读性。不信？我们先来看看下面的代码。

当你读到下面的代码，你会觉得这个代码是什么意思？

widget->repaint(false);

是不要repaint吗？还是别的什么意思？看了文档后，我们才知道这个参数是immediate，也就是说，false代表不立即重画，true代码立即重画。

Windows API中也有这样一个函数：InvalidateRect，当你看到下面的代码，你会觉得是什么意思？

InvalidateRect(hwnd, lpRect, false);

我们先不说InvalidateRect这个函数名取得有多糟糕，我们先说一下那个false参数？invalidate意为“让XXX无效”，false是什么意思？双重否定？是肯定的意思？如果你看到这样的代码，你会相当的费解的。于是，你要去看一下文档，或是InvalidateRect的函数定义，你会看到那个参数是 BOOL bErase，意思是，是否要重画背景。

这样的事情有很多，再看下面的代码，想把str中的”%USER%”替换成真实的用户名：

str.replace("%USER%", user, false); // Qt 3

TNND，那个false是什么意思？不替换吗？还是别的什么意思，看了文档才知道，false代码大小写不敏感的替换。

其实，如果你使用枚举变量/常量，而不是bool变量，你会让你的代码更易读，如：

…

阅读全文 Read More

(32 人打了分，平均分： 3.78 )

重构代码的7个阶段

2011年08月16日陈皓评论 78 条评论 70,239 人阅读

你曾去想重构一个很老的模块，但是你只看了一眼你就恶心极了。文档，奇怪的函数和类的命名，等等，整个模块就像一个带着脚镣的衣衫褴褛的人，虽然能走，但是其已经让人感到很不舒服。面对这种情况，真正的程序员会是不会认输的，他们会接受挑战认真分析，那怕重写也在所不惜。最终那个模块会被他们重构，就像以前和大家介绍过的那些令人销魂的编程方式中的屠宰式编程一样。下面是重构代码的几个阶段，文章来自：The 7 stages of refactoring，下面的翻译只是意译。

第一阶段 – 绝望

在你开始去查看你想要重构的模块的，你会觉得好像很简单，这里需要改一个类，那里需要改两到三个函数，重写几个函数，看上去没什么大不了的，一两天就搞定了。于是你着手开始重构，然后当你调整重构了一些代码，比如改了一些命名，修理了一些逻辑，渐渐地，你会发现这个怪物原来体型这么大，你会看到与代码不符甚至含糊不清的注释，完全摸不着头脑的数据结构，还有一些看似不需要方法被调了几次，你还会发现无法搞清一个函数调用链上的逻辑。你感到这个事可能一周都搞不定，你开始绝望了。

第二阶段 – 找最简单的做

你承认你要重构的这个模块就是一个可怕的怪物，不是一两下就可以搞定的，于是你开始着干一些简单的事，比如重新命名一下几个函数，移除一些代码的阻碍，产生几个常量来消除magic number，等等，你知道这样做至少不会让代码变得更糟糕。

第三阶段 – 再次绝望

但是接下来的事会让你再次撞墙。你会发现那些代码的瑕疵是些不痛不痒的事，改正这些事完全于事无补，你应该要做的事就是重写所有的东西。但是你却没有时间这么干，而这些代码剪不乱理还乱，耦合得太多，让你再一次绝望。所以，你只能部分重写那些不会花太多时间的部分，这样至少可以让这些老的代码能被更多的重用。虽然不完美，但是至少可以试试。

…

阅读全文 Read More

(34 人打了分，平均分： 4.24 )

一个空格引发的惨剧

2011年06月20日陈皓评论 106 条评论 166,747 人阅读

你是否相信如果你的程序里没有检查一个变量会导致怎么系统瘫痪？无论你相不相信，这是我一个亲身经历过的案例，你可以在本站的程序员那些悲催的事儿中找到很多这样的事。这样的事昨天在发生，今天同样在发生。Unix40多年了，在这40年里，程序员发生过各种各样的的惨剧，但是大多数的事情一而再再而三的重演。

今天的你，可能在开发者各种各样NB的系统，你会相信你的一个空格也能导致系统瘫痪吗？也许你可能很难相信这个事。不过，再下面这个事将告诉你这个血淋淋的事实 —— 一个空格产生的bug可以让你的系统瘫痪。

bumblebee是一个开源项目，这个名字也就是变形金刚里的大黄蜂，这个项目是这样介绍自己的——

bumblebee is Optimus support for Linux, with real offloading, and not switchable graphics.. More important.. it works on Optimus Laptops without a graphical multiplexer..

Optimus 是NVIDIA的“优驰”技术，其可以将您的笔记本电脑PC提升到绝佳状态，提供出色的图形性能，并在需要时延长电池续航时间。这个项目是把这个技术移到Linux上来。

这个项目本来不出名，不过，程序在其安装脚本install.sh里的一个bug让这个项目一下子成了全世界最瞩目的项目，这个bug的fix如下：

@@ -348,7 +348,7 @@ case "$DISTRO" in
-  rm -rf /usr /lib/nvidia-current/xorg/xorg
+  rm -rf /usr/lib/nvidia-current/xorg/xorg

看明白了吗？空格。这个空格会导致什么样的问题呢？呵呵。你有没有感到菊花一紧？这个bug绝对的霸气外露！真是验证了“如何写出无法维护代码”的那句话——“测试你的程序是一种懦夫的行为”。

不过，最精彩还不是这个bug，而是全世界程序员的对这个bug 的 code review comments，真的相当的欢乐。请强势围望！

…

阅读全文 Read More

(28 人打了分，平均分： 3.89 )

如何写出无法维护的代码

2011年06月03日陈皓评论 147 条评论 279,611 人阅读

酷壳里有很多我觉得很不错的文章，但是访问量最大的却是那篇《6个变态的Hello World》，和它能在本站右边栏“全站热门”中出现的还有“如何加密源代码”，以及编程真难啊等这样的文章。可见本站的读者们的偏好，我也相信你们都是“身怀绝技”的程序员。所以，今天给大家推荐这篇文章，相信一定能触动大家的兴奋点。

这篇文章的原文在这里（http://mindprod.com/jgloss/unmain.html），我看完后我想说——

什么叫“创造力”，创造力就是——就算是要干一件烂事都能干得那么漂亮那么有创意的能力。
什么叫“抓狂”，抓狂就是——以一种沉着老练的不屈不挠的一本正经的精神一点一点把你推向崩溃的边缘。

我把文章节选了一些，也并没有完全翻译，简译一下，也加入了一些自己的调侃。对于有下面这些编程习惯的朋友，请大家对号入座。另外，维护程序的朋友们，你们死定了！！

If builders built buildings the way programmers write programs, then the first woodpecker that came along would destroy civilization. （如果建筑师盖房子就像程序员写程序一样，那么，第一只到来的啄木鸟就能毁掉我们的文明）

~ Gerald Weinberg (born: 1933-10-27 age: 77) Weinberg’s Second Law

程序命名

容易输入的名字。比如：Fred，asdf
单字母的变量名。比如：a,b,c, x,y,z（陈皓注：如果不够用，可以考虑a1,a2,a3,a4,….）
有创意地拼写错误。比如：SetPintleOpening， SetPintalClosing。这样可以让人很难搜索代码。
抽象。比如：ProcessData, DoIt, GetData… 抽象到就跟什么都没说一样。
缩写。比如：WTF，RTFSC …… （陈皓注：使用拼音缩写也同样给力，比如： BT，TMD，TJJTDS）
随机大写字母。比如：gEtnuMbER..
重用命名。在内嵌的语句块中使用相同的变量名有奇效。
使用重音字母。比如：int ínt（注：第二个 ínt不是int）
使用下划线。比如：_, __, ___。
使用不同的语言。比如混用英语，德语，或是中文拼音。
使用字符命名。比如：slash, asterix, comma…
使用无关的单词。比如：god, superman, iloveu….
混淆l和1。字母l和数字1有时候是看不出来的。

…

阅读全文 Read More

(70 人打了分，平均分： 4.39 )

Amazon的书为什么卖到了$2000万

2011年04月28日陈皓评论 28 条评论 30,133 人阅读

最近，Amazon的新闻比较多，除了Amazon的云平台宕机外，还有一个被热炒的新闻是在Amazon的书店里，有一本书要买$23,698,655.93美元，相当于1亿5千万人民币（如下图所示），这个事情是由UC Berkeley的生物学家Michael Eisen发现的，然后他在他的博客上写了一篇文章来说明这个事情。

这本书是1992年，现在绝版了，生物学家决定上Amazon找一下，结果看到了有两本新书，还有一些二手的，二手书价比较正常，但是那两个新书的价都上了百万。这个生物学家还写了邮件给原作者和原作者开了玩笑。呵呵。

一般人可能就把这个事当成个笑话了，不过，教授就是教授，它还认真的研究了一下为什么会这样。

…

阅读全文 Read More

(21 人打了分，平均分： 4.05 )

Linux 2.6.39-rc3的一个插曲

2011年04月27日陈皓评论 118 条评论 69,907 人阅读

2011年4月12日，Linux 2.6.39-rc3发布了，Linus Torvalds写了一个发布邮件，其中包含了一个长长的为这个版本做过贡献的人员名单，这个名单中有很多看上去应该是中国人的名字，我挺为他们感到骄傲的（不知道你是否还记得以前本站的”Linux是由谁写的“）。

不过，没过一会，发现了一个bug，经过大家的调查（2.6.38版没有发现这个问题），很快，找到了原因，是因为一个内存地址的问题，一个叫Yinghai Lu的人（看其名字应该是中国人，其邮件是@kernel.org）找到了原因—— radeon card使用了一个不正确的内存地址[0xa0000000 – 0xc000000]。Joerg Roedel跟贴说，这个地址超出了4GB的内存，然后他和Alex Deucher聊了一会，觉得不应该是这个问题，因为这个地址应该是GPU的，而不是系统内存的。

好像，Yinghai Lu没有理会他们说的不应该是这个问题，给出了个fix：

diff --git a/arch/x86/kernel/aperture_64.c b/arch/x86/kernel/aperture_64.c
index 86d1ad4..3b6a9d5 100644
--- a/arch/x86/kernel/aperture_64.c
+++ b/arch/x86/kernel/aperture_64.c
@@ -83,7 +83,7 @@ static u32 __init allocate_aperture(void)
 	 * so don't use 512M below as gart iommu, leave the space for kernel
 	 * code for safe
 	 */
-	addr = memblock_find_in_range(0, 1ULL<<32, aper_size, 512ULL<<20);
+	addr = memblock_find_in_range(0, 1ULL<<32, aper_size, 512ULL<<21);
  	if (addr == MEMBLOCK_ERROR || addr + aper_size > 0xffffffff) {
 		printk(KERN_ERR
 			"Cannot allocate aperture memory hole (%lx,%uK)\n",

看到这个fix，Linus Torvalds不高兴了，他回贴问道：

为什么全都是Magic Numbers？
为什么0x80000000就那么特殊？
为什么我们这样改就行？

还说了这样一句话——

…

阅读全文 Read More

(30 人打了分，平均分： 4.27 )

酷壳 – CoolShell

享受编程和技术所带来的快乐 – Coding Your Ambition

Browsed by
标签： Coding