Erning.write()

Reloading

中文文档格式规范

原文:中文文档格式规范

格式规范的目的是为了提供一些准则、方针,使得文档的风格一致。

以下的规则并没有声明不能变动,也不暗示這些规则比其他方式都要好,但如果所有人的编辑方式都一致,我们的文档会更易于阅读和使用,并让撰写和编辑变得更加方便。

中英文混合

在科技行业,英文的专有名词或者通俗缩写非常多,因此文档内中英文混合排版不可避免。

选择明确、简洁的词汇

在选择使用中文还是英文时,我们以最能明确、简洁地表达意图为原则。例如在没有被广泛接受之前,NBA 不要写成“北美职业篮球联赛”。

专有名词使用正确的大小写

正确:

使用 GitHub 登录

错误:

使用 Github 登录

使用 github 登录

空格

中英文之间需要增加空格

正确:

本站点使用 Jekyll 搭建,应用 HPSTR 主题。文章保存在 _posts 目录下。

错误:

本站点使用Jekyll搭建,应用HPSTR主题。文章保存在_posts目录下。

完整的正确用法:

请尽量避免直接使用系统自带的 Ruby,推荐使用 rbenv 来管理本地 Ruby 运行环境,同时使用 ruby-build 来安装 Ruby,现使用的 Ruby 版本为 2.1.1。

中文与数字之间需要增加空格

正确:

今天出去买菜花了 5000 元

错误:

今天出去买菜花了 5000元

今天出去买菜花了5000元

数字与单位之间需要增加空格

正确:

我家的带宽有 1 Gbps,硬盘一共有 10 TB。

错误:

我家的带宽有 1Gbps,硬盘一共有 10TB。

标点符号

中文排版时,一律使用全角(fullwidth)中文标点

正确:

嗨!你知道吗?今天前台的小妹跟我说“喵”了哎!

错误:

嗨!你知道吗?今天前台的小妹跟我说”喵”了哎!

嗨!你知道吗?今天前台的小妹跟我说”喵”了哎!

中英排版时,一律使用全角(fullwidth)中文标点

正确:

核磁共振成像(NMRI)是什么原理都不知道?JFGI!

错误:

核磁共振成像(NMRI)是什么原理都不知道?JFGI!

核磁共振成像(NMRI)是什么原理都不知道?JFGI!

中英排版时,遇到完整的英文整句,整句内容使用半角(halfwidth)中文标点

正确:

乔帮主那句话怎么说的?“Stay hungry, stay foolish.”

错误:

乔帮主那句话怎么说的?“Stay hungry,stay foolish。”

其他

中文链接增加空格

建议用法:

访问我们网站的最新动态,请 点击这里 进行订阅。

对比用法:

访问我们网站的最新动态,请点击这里进行订阅。

简体中文与正体(繁体)中文

建议使用简体中文。

地区词汇

建议使用中国大陆通用的词汇,例如使用“程序”,避免使用“程式”。

相关链接

GitCorp Flow - 安居客Git开发流程规范

代码仓库 – Git Repositories

原始代码仓库

在这篇文章的例子中,我们以git@git.corp.anjuke.com:corp/flow-demo.git为原始代码仓库。文章后面提到的origin都是指原始代码仓库。

origin上只包含有三个分支,masterbetaga;每一个发布的版本将有一个tag。

  • master 主要的开发分支,待发布的新功能都在这个分支上。通常对这个分支进行每日构建、集成测试等;新的功能开发也都在这个分支的基础上进行。通常这个分支是最新的。

  • beta 这个分支的代码是已经部署到预发布环境的指针,通常其HEAD指向当前的预发布版本。当BETA环境有重要的hotfix时,在这个分支上开始;同时这个hotfix还需要合并回master。

  • ga 这个分支是部署到对外公开的环境,通常其HEAD指向当前的对外公开版本。当GA环境有重要的hotfix时,在这个分支上开始;同时这个hotfix还需要合并回master;如果必要改hotfix也将合并至beta分支。

ga/beta分支的HEAD会被release发布命令改变。

本地开发仓库

当我们进行项目开发的时候,需要将origin克隆到本地,这时我们称呼本地的git仓库为本地开发仓库。下面这个命令将原始的flow-demo.git克隆到本地。

$ git clone git@git.corp.anjuke.com:corp/flow-demo.git

在本地仓库查看所有分支

$ git branch -a

将显示

* master
  remotes/origin/beta
  remotes/origin/ga
  remotes/origin/master

Readme驱动开发

中文翻译:陈磊 AReverie
英文原文:Tom Preston-Werner

我最近听到很多关于测试驱动开发、行为驱动开发、极限编程和SCRUM站立会议 以及其他一切如何开发出更好的软件的各种方法论及技术,然而除非开发出来的软件满足使用者的需求,否则都是一纸空谈。我换种说法吧,对于错误规格的完美实现毫无价值可言。基于同样的原则,一座没有书卷而华丽修缮的图书馆也近乎无用。如果你的软件没有解决正确的问题或者根本没人知道它到底干嘛的,那可就不好玩了。

很好,那我们怎么解决这个问题呢?实际上比你想的要来的简单,并且其重要都足以单独列出一段。

先写Readme

首先,就像前面说的,在你动手写任何代码、测试、行为或者情景甚至任何东西前。别急别急,我明白我们都是程序猿,不是技术文枪手!但这就是你没想明白的地方。为一个软件写Readme着实非常有必要性。在给你的软件写点什么东西前,你根本不知道你要编写什么样的代码。在人人喊打的瀑布型设计和人见人爱的敏捷开发之间,我们似乎漏了点什么。别误会,瀑布型设计代价太大。它能把一个细致入微的庞大系统变成一个细致入微却全盘错误的系统。当初砍掉它是个正确的做法,但做法却矫枉过正。如今我们的项目里只有短小、糟糕的文档甚至完全不见踪影。你能想象有些项目完全没有Readme吗!

简直难以接受!在成堆的技术规格和完全没规格之间,必然会有个平衡点。那个平衡点就是朴素简明的Readme。

将Readme驱动开发(下文简称RDD)区别于文档驱动开发(下文简称DDD)十分重要。RDD可以理解成DDD的一个有限版本或子集。通过将你的设计文档精简成一个旨在介绍软件的单个文件,RDD能帮助你免于重蹈DDD而出现的瀑布型开发过程中出现冗长而过分细致的规格。同时,它能帮助你保持库的精简和模块化。这样一个简单的方法能帮助您免去繁琐的流程保证项目朝着正确的方向前进。

通过写第一个Readme,您能受益于以下这些显著的优势:

  • 最为重要的一点是,您给于了自己一次重新审视项目,又无需每次为了改变主意而去修改代码而花去开销的机会,例如整体应该如何组织、公用API里到底应该包含哪些东西。还记得您第一次写自动化测试代码,意识到揪出全部的错误从而防止那些问题悄悄跑进代码里去吗?在项目真正编码前写一个Reame的感觉是如出一辙的。

  • 为了明确应该实现什么而去写Readme会产生一些副产品,您会得到一份写的非常棒的文档。当您在项目伊始,也就是兴奋度和动机处于最高的阶段,写一个文档会十分容易。事后再补Readme将是一种绝对的障碍,并且您会发现遗漏了许多重要的细节。

  • 如果您与一群开发者一起协同工作,将会发现会从Readme收益颇多。如果其他成员在您尚未完成项目前便可以读到这份Readme,他们将大可放心的在将与您项目有交互的代码上开始工作。如果没有预先定义好的接口,团队只能顺序地编码或者面临重新实现大量代码的窘境。

  • 基于白纸黑字的讨论将会容易的多,而在一个没有任何成文内容的讨论话题上,事情往往会演变成争论不休。把建议的解决方案写下来这样一个简单的行动,代表了一个具体的想法,从而能被讨论,迭代发展下去。

把给您项目写Readme的过程当作一种真正的创造活动吧,这是您充满闪光的想法应该被表达的地方,这份文件的本意应当是阐述您的创造力和表现力。Readme应当是您代码中最为重要的一个文档,适当的做法就是首先写Readme。

The Twelve-Factor App

中文翻译:梁山
英文原文:Adam Wiggins

翻译问题反馈

简介

如今,软件通常会作为一种服务来交付,它们被称为“互联网应用程序”(web apps),或“软件即服务”(SaaS)。这篇“互联网应用的十二要素”为构建如下的互联网应用程序提供了指导方法:

  • 使用标准化流程自动配置,从而使新的开发者花费最少的学习成本加入这个项目;
  • 和操作系统之间尽可能的划清界限,在各个系统中提供最大的可移植性
  • 适合部署在现代的云计算平台,从而在服务器和系统管理方面节省资源;
  • 将开发环境和生产环境的差异降至最低,并使用持续交付实施敏捷开发;
  • 可以在工具、架构和开发流程不发生明显变化的前提下实现扩展

这套理论适用于任意语言和后端服务(数据库、消息队列、缓存等)开发的应用程序。

背景

本文的贡献者参与过数以百计的应用程序的开发和部署,并通过Heroku平台间接见证了数十万应用程序的开发,运作以及扩展的过程。

本文综合了我们关于SaaS应用几乎所有的经验和智慧,是开发此类应用的理想实践标准,并特别关注于应用程序如何保持良性成长,开发者之间如何进行有效的代码协作,以及如何避免软件污染

我们的初衷是分享在现代软件开发过程中发现的一些系统性问题,并加深对这些问题的认识。我们提供了讨论这些问题时所需的共享词汇,同时使用相关术语给出一套针对这些问题的广义解决方案。本文格式的灵感来自于Martin Fowler的书籍:Patterns of Enterprise Application ArchitectureRefactoring

读者应该是哪些人?

任何SaaS应用的开发人员;部署和管理此类应用的运维工程师。

Home Network Setup

家庭网络设置的需求

LAN

在家里,应该做到在任何地方都可以连上网络,而不是必须坐在电脑桌前;目前可以上网的移动设备比电脑还多。因此Wifi网络是必须的。

如果还在使用百兆的网络,拷贝一份20G的高清电影你需要30多分钟。而如果使用千兆网络,同样拷贝一份20G的电影,只需要3分钟多一些。当然硬盘可能不够快,以致实际上需要10多分钟才能完成。所以需要千兆网络交换机。

需要设备一接上,不需要配置就应该能够互连。IPv4的情况下,还是DHCP服务器自动分配IP比较方便的。

Internet

家庭网络内的设备都需要访问互联网,需要一个路由器做网关。

目前运营商为家庭用户提供的互联网接入方式还是以PPPoE为主。

运营商提供的域名解析服务器不靠谱,部分域名还被污染。用8.8.8.8或opendns这样的解析服务可能无法解析到最佳网络连接的主机。自建的解析服务器还可以解析内部网络的主机。

架一个HTTP代理服务器能够很大程度提高互联网页面的访问速度。

翻墙,这属于基础设置。需要做到网络层的翻墙,简单的HTTP代理不够。

8 Puzzle (Python)

重排九宫

+---+---+---+      +---+---+---+
| 1 | 2 | 3 |      | 8 | 7 | 6 |
+---+---+---+      +---+---+---+
| 4 | 5 | 6 |  ==> | 5 | 4 | 3 |
+---+---+---+      +---+---+---+
| 7 | 8 |   |      | 2 | 1 |   |
+---+---+---+      +---+---+---+

$ 8puzzle.py -f2
# 30
Number of states enqueued = 14754

Mac Tips 3 - Startup Options

Startup keyboard shortcuts

  • C —– Start from a bootable disc (DVD, CD)
  • T —– Start in FireWire target disk mode
  • N —– Start from NetBoot server
  • X —– Force Mac OS X startup (if non-Mac OS X startup volumes are present)

  • Shift —– Boot in Safe Mode. Effectively the same as passing “-x” in Kernel Flags, and causes most caches to be ignored by the booter.

  • Command-S —– Boot in Single User Mode. Effectively the same as passing “-s” in Kernel Flags, and causes the system to boot to an interactive shell with no system services started.

  • Command-V —– Boot in Verbose Mode. Effectively the same as passing “-v” in Kernel Flags, and causes the system to boot to verbose text logging before starting the graphical user interface.

  • 3 2 —– Boot with the 32-bit kernel. Effectively the same as passing “arch=i386″ in Kernel Flags, and causes the system to prefer the 32-bit kernel on systems that would otherwise boot the 64-bit kernel.

  • 6 4 —– Boot with the 64-bit kernel (if supported on this system). Effectively the same as passing “arch=x86_64″ in Kernel Flags, and causes the system to prefer the 64-bit kernel on systems that would otherwise boot the 32-bit kernel. If the 64-bit kernel is not supported, the option is ignored.

Hold down the mouse’s primary key during startup. On a two- or three-button mouse, the primary key is usually the left button. This shortcut will eject a CD or DVD from the optical drive.

Hold Command + Option + p + r during startup. This zaps the PRAM (Parameter RAM), an option that long-time Mac users will remember. Press and hold the key combination until you hear the second set of chimes. Zapping the PRAM returns it to its default configuration for display and video settings, time and date settings, speaker volume, and DVD region settings.

Mac Tips 2

Disable Spotlight in Mac OS X 10.6

Disabling Spotlight in Snow Leopard is pretty easy, launch the Terminal and type the following command:

sudo mdutil -a -i off

This tells the Spotlight manager to disable all indexing on all volumes, the command will require your administrative password to execute.

Re-enabling Spotlight in Mac OS X 10.6 Snow Leopard is just as easy, just reverse the command to:

sudo mdutil -a -i on

Now Spotlight indexing will be back on and work as usual.

—– osxdaily

sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.metadata.mds.plist
sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.metadata.mds.plist

There Was No One Left to Speak Out

Als die Nazis die Kommunisten holten,
habe ich geschwiegen;
ich war ja kein Kommunist.

Als sie die Sozialdemokraten einsperrten,
habe ich geschwiegen;
ich war ja kein Sozialdemokrat.

Als sie die Gewerkschafter holten,
habe ich nicht protestiert;
ich war ja kein Gewerkschafter.

Als sie die Juden holten,
habe ich geschwiegen;
ich war ja kein Jude.