索引: 用中文代码作示例的编程教程

[nobodxbodon]

之前写了一个Java入门教程, 在Java区有链接. 有空请各位斧正.
现在考虑下一个教程的主题, 不知有什么建议.
@jeromechan 看到你之前的译作https://github.com/jeromechan/programming-principles-cn, 想必有些感想?

[nobodxbodon]

下面是想到的. 还有哪些可能的方向呢?

• 翻译经典教程, 将示例代码中文化
• 入门类: 如编程语言, 热门框架/库
• 进阶类: @jeffreybaoshenlee 提议用比较接近工程的示例编写, 最好贯穿一个教程
• 从0开始写XX: 操作系统, 编程语言(可以同时为中文语言的实现作实验), 输入法

在初期人力有限的情况下, 考虑从工作量小, 周期短, 受众广的方向做起.

[ice1000]

我修改了下 Kotlin 的和 Haskell 的，现在稍微能看了，以前那个 Hello World 式的实例感觉十分挫 23333

[nobodxbodon]

现在的示例程序并不为了演示编程语言本身的特性, 而是对中文命名进行可行性验证. 原则上越简单的越好. 如果想要用中文代码演示编程语言本身特性, 欢迎写一些针对某一编程语言的入门教程.

[ice1000]

我已经证明了 Kotlin 中可以完美汉化 @Test

[nobodxbodon]

看了你的例程, 觉得在例程里展示一种编程语言中尽量多可以中文化的语言特性其实挺不错的. 大赞一下.

[nobodxbodon]

Teaching Front End Programming in Your Own Culture里提到在编程教学中引入中国文化特色:

A team of three heroes founded to save the country. var 蜀 = ['刘备', '关羽', '张飞'];
Their leader(刘备) then hired two military advisers. 蜀.splice(1, 0, '诸葛亮', '庞统')
One of them died in a battle. 蜀.splice(2, 1)
Two of the founders died in battles but more members joined. 蜀.splice(2, 2, '刘婵', '赵云', '廖化')
Later the leader (刘备) died and his son(刘婵) became the leader of the team. 蜀.copyWithin(0, 2, 3).splice(2, 1)

同作者已经有比较中文特色的JS教程, 但代码本身还未完全中文化. 已提建议何不把代码本身中文化?

[nobodxbodon]

在2D图形编程方面初步尝试了汉化p5js接口实现的中文编程演示#20 (comment) . 在osc发了贴. 相信影响总是慢慢积累的.
受限于webgl模式下的问题 program-in-chinese/p5js_in_chinese#1 暂时不能演示3D的效果.

[nobodxbodon]

实用教程的可能方向:

• 希望大家多帮忙完善下关键字 CTS#2 (comment) 提到微信小程序
• 跨界: 哪些中文非IT领域会偏好中文API, 编程/脚本语言? #19 (comment) 提到数据抓取/处理/分析的需求.

[nobodxbodon]

刚开始写CTS的0基础入门笔记, 请多提批评. 特此 @htwx .

[nobodxbodon]

如此,打算着手Scala以及相关框架的笔记/短教程.
初步打算基于Programming in Scala(带用中文命名示例代码的学习笔记已开新库https://github.com/program-in-chinese/Programming_in_Scala_study_notes_zh). 因为Functional Programming in Scala更进阶.
另外, Awesome Scala汇集了Scala的库/框架/应用.

[nobodxbodon]

基于讨论, 开始一个最小的尝试. 对vuejs的官方入门代码进行中文化. 目标是完成这个短教程的7个示例. 请对命名方式多提意见. 谢谢.

[nobodxbodon]

已将vuejs入门中文化的小结发布在中文代码示例教程之Vuejs入门&后续计划一文中. 顺便列出了以后进行类似实践的框架. 下一个在占据市场80%的PHP框架中选择, 考虑Laravel.

[nobodxbodon]

@jeffreybaoshenlee 请教一下, 如何知道哪些外文IT类书籍最需要翻译(从市场角度看)? 译著的发布渠道有哪些? 如果想对其中的示例代码使用中文命名, 哪些渠道最可能愿意接受?

[jeffreybaoshenlee]

@nobodxbodon 抱歉，我對譯著發行等業務方面的問題，不太瞭解。我按照自己的理解回答一下，供您參考：

目前，還是講述具體技術的外文 IT 書較受歡迎，也就是那種看了之後直接就能用來編程或做項目的。這種書，最好是能夠融入作者自身的獨特經歷或心得，而不能僅僅是把相關素材簡單地拼湊起來。
其次，可能還有一些講解開發流程的書（我指的是廣義的開發，不僅包括編寫代碼/編程，還包括設計、管理、維護、測試、運營，乃至人事）。
第三，就是一些經典書籍的新版或續作，比方說，如果講解某個話題的權威書籍出了新版，那麼讀者可能很想看到中文版。

發佈渠道麼，傳統的渠道可能還是出版社。
新的渠道，可以考慮博客或開源平臺，也就是用開源項目或維基項目的形式來翻譯。
（我不想說，但是不得不說的問題，就是版權。如果外文原作不在公有領域，而且不是可以自由衍生的作品，那可能就需要解決版權問題了。具體怎麼解決，我還沒頭緒。）
（另外，還有一種渠道就是電子書發行平臺。這個我還沒有具體的想法。如果確實遇到了亟待翻譯的作品，或許可以與那些平臺的工作人員溝通一下，看看怎麼發佈。有些出版社，也開始創建這種平臺了。）

示例代碼用中文命名，這個對於傳統的印刷書籍來說，可能需要與出版方溝通一番（我還沒嘗試過）。
但是對於電子書，或者新型渠道來說，可以一試。（然而對於既不在公有領域，又不能自由衍生的作品來說，還是繞不過原作者這一關。）

最後，我又想到，如果打算先試試水，那可以在網上找找那種能夠自由運用的作品，我記得有一些作者，已經把自己的作品發佈成這種形式了。另外也可以拿自由教材（可能就是類似 WikiBooks【維基教科書】 的東西吧）練手？

[nobodxbodon]

@jeffreybaoshenlee 多谢详细介绍! 也许开始从单篇文章入手更现实一些(投入相对小的多). 比如这种: https://www.ibm.com/developerworks/cn/xml/x-scalaxml/
接着就要找像你说的版权宽松的作品, 比如Creative Commons的? 最好来源的平台也支持发布翻译版本, 就省去再找发布平台了.

[jeffreybaoshenlee]

@nobodxbodon 嗯，CC 協議下面有很多變種，限制程度各有不同，可能需要仔細辨別一下（https://en.wikipedia.org/wiki/Creative_Commons_license#Seven_regularly_used_licenses ）。

另外，或許還有其它一些版權協議也值得關注，例如 MIT。詳細對比可以參見：https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses 。雖然在我印象中，這些協議主要是用於軟件的，但是近年來，也有很多人將它們套用在文章、圖片、視頻等資源上面。

另外，我也喜歡那種本身就融入了翻譯機制的文章發佈平臺，哈哈。

[nobodxbodon]

@duotai 刚收到这个:

requested approval for a third-party application to access 中文编程 organization resources via the GitHub API:

"GitBook" from GitBook

请问是打算在gitbook进行中文编程的相关写作吗? 还有它能access哪些resources呢?

[nobodxbodon]

打算写一个Python快速入门的原型, 内容涵盖官方入门文档三四五章中最常用的部分, 示例代码可能选材于西游记某个故事(之前的尝试在"西游记"主题Python入门示例尝试-数据结构 5.1-5.1.2). 比较想参考现实项目的开发过程, 从一个最简单的需求(最简短的故事)开始, 对应最简单的代码, 然后逐渐扩大需求(逐步完善故事), 随之扩充代码并同时演示各种语法/结构对于代码的作用. 最终的代码效果也许是个类似说故事的过程. 下面演示了非常粗略的构思, 请多提建议.

$ python 三打白骨精.py
唐僧 孙悟空 猪八戒 沙僧 在取经路上  <--- 这里数组/列表初始化, 遍历
白骨精变作少妇           <---- 下面是三个循环, 对应三打
孙悟空将她打倒
唐僧念了一遍紧箍咒
白骨精变作老妇人           <---- 二次循环
孙悟空将她打倒
唐僧念了二十遍紧箍咒
白骨精变作老公公           <---- 三次循环
孙悟空将他打死              <---- 打倒/打死 基于循环次数作条件判断; '他/她'通过{形象->性别}字典实现
唐僧念了好几遍紧箍咒   <---- 一/二十/好几 通过{次数->字符串}的字典实现
唐僧将孙悟空赶走          <---- 列表remove操作
剩下师徒3人继续赶路   <-----列表len()

[jeffreybaoshenlee]

@nobodxbodon 哈哈，西遊記題材很好。如果加上互動（命令行式的交互？），可能就是個文字冒險遊戲啦。

[nobodxbodon]

@jeffreybaoshenlee 的确! 刚看了一下官方入门居然好像没提到获取键盘输入. 感觉应该属于常用功能.
先从最小开始, 试试按照渐进式开发进行编写. 常见的入门教程好像都按照编程语言本身的功能分块介绍, 而不是围绕一个主题展开来按需求介绍功能. 如果看到过这种类似思路的教程请推介一下.

[jeffreybaoshenlee]

@nobodxbodon 我想起很久以前看到過的一本書，《深入淺出面向對象分析與設計》（英文原名《Head First Object-Oriented Analysis and Design 》），它不是為了講解某個具體編程語言的，而是為了講解面向對象（OO）這個理念。

整本書都用一個較大的例子來貫穿，也就是根據用戶輸入的起點與終點，給出地鐵換車方案。前面各章所講的小知識點（例如怎麼拆解需求，怎麼把需求映射到類，怎麼設計類的字段，怎麼決定類與對象之間的相互關係，怎麼用對象來表示現實世界的事物等等），逐漸匯聚成最後這個可以運行的大例子。

[nobodxbodon]

@jeffreybaoshenlee 多谢! 刚看了一下amazon, 虽然是4星, 不过有不少一星评论, 似乎有些非编程新手对它的组织有不少意见. 考虑先把它学习一下, 以供借鉴. 顺便把示例代码中文化一下 :)

[nobodxbodon]

@jeffreybaoshenlee 刚粗略浏览了一下: https://zhuanlan.zhihu.com/p/41920600 好像地铁例子是最后一章的, 之前还有三个不同项目. 不过大思路还是很值得借鉴. 多谢.

[jeffreybaoshenlee]

@nobodxbodon 嗯，現在回想起來，最後那個大例子，在複雜程度和廣度上面，可能與前面那些小例子之間差得比較大。怎樣組織素材，怎樣循序講解，確實很需要思考。

我想到反向推理的辦法，先擬構一個心目中的成品，然後看看能不能把它拆解成依賴關係較為明晰的幾個小模塊，接下來按照依賴關係，重新梳理一遍：先講不依賴其它模塊（或者說，在依賴樹中處於樹葉地位的）單元，再講本身依賴其它模塊，同時也為另一些模塊所依賴的單元，最後講只依賴其它模塊的樹根單元。不過，我這種想法還是過於理想了，實際上各模塊之間或許是循環依賴的關係，沒辦法這樣輕易地拆解，而且處於樹葉地位的單元，在實現細節上，有可能比其它單元更複雜（這種單元，或許根本就不用納入教程，只是說調用某個軟件包或庫就行了）。

[nobodxbodon]

第一次看到在示例代码中用非英文母语命名的编程书籍. 日语版的初めてのJavaScript 第3版. 示例代码:

class Person {
  constructor(name) {
    this.name = name;
    this.id = Person.nextId++;
  }
}
Person.nextId = 0;
const 一郎 = new Person("一郎"), /* id 0 */
      次郎 = new Person("次郎"), /* id 1 */
      三郎 = new Person("三郎"), /* id 2 */
      四郎 = new Person("四郎"); /* id 3 */
const arr = [一郎, 次郎, 三郎, 四郎];

/* 1. IDを使って直接比較 */
console.log(arr.find(p => p.id === 三郎.id)); // Person { name: '三郎', id: 2 }
/* 2. thisを利用。thisを定数「三郎」に指定 */
console.log(arr.find(function(p) {return p.id === this.id}, 三郎));
                                              // Person { name: '三郎', id: 2 }
/* アロー関数ではthisは「語彙的に（lexically）」に束縛される（6章参照） */
console.log(arr.find(p => p.id === this.id, 三郎)); // undefined

期待中文示例代码的编程书籍早日面世.

另外, 看来日语命名在日本开发者中也是有阻力的, 日本語識別子（変数名や関数名）を好まれない方がいらっしゃるようですので - "似乎有些人不喜欢日语标识符（变量名和函数名）"
无论如何, 日本出版商在母语命名上还是敢于尝试的.

[nobodxbodon]

刚发文首次发现在例程中使用日语命名的编程书籍. 其中译者的一句话(2016 年 12 月)颇值得推敲:

これからは、日本国内をターゲットにした開発では徐々に日本語識別子が使われることになるのでしょう

在线翻译如下:

"今后，以日本国内为目标的开发会逐渐使用日语标识符吧"

有兴趣的可以研究一下日本业界是出台了什么命名规范推广日语命名吗?

[jeffreybaoshenlee]

@nobodxbodon 哈哈，你又發現好東西啦。

我感覺，開發者可以先從自己寫的博客文章或電子書入手，試着把裡面的範例代碼，用中文編程風格寫出來，或者給出中英文兩個版本，構成雙語對照。結合相應的 API（例如你寫的那個工具）來實現雙語對照，應該是可以考慮的。

補記：代碼語言轉換工具，將來或許可以考慮反向使用，例如把其它語言轉為英文。

[nobodxbodon]

@jeffreybaoshenlee

開發者可以先從自己寫的博客文章或電子書入手，試着把裡面的範例代碼，用中文編程風格寫出來

嗯, 在知乎专栏里一直在写这样的短文. 可惜在其他地方还没看到这样的实践. 如有发现请告知.

关于源代码机器翻译, 其实做下去会遇到和自然语言机器翻译类似的问题. 就是词汇的歧义. 当然会比自然语言好一些, 因为命名往往使用的是最正式(非口语化)的词汇, 连接词的使用也较少, 而且基本没有完整语句. 即便如此, 也至少存在词性问题, 比如此文的例子中BasicCalculator, Basic在內建词典中有名词/形容词几种词义:

n. 基本原理, 要素, 基本规律
a. 基本的, 碱性的
(计算机)BASIC语言

而现在是用的最简单的首个词义, 就是名词的"基本原理". 改进就需要一些自然语言处理的方法.

或許可以考慮反向使用，例如把其它語言轉為英文。

是的. 不过使用场景还不明确. 如果是为第三方使用而将少数公开API添加英文版本, 大可以人工翻译保持准确度. 如果是出于某种原因必须转换为英文命名, 但不需保证可读性, 这时候机器翻译会比较适用.

[jeffreybaoshenlee]

@nobodxbodon 嗯，反向使用的問題我也沒有具體想好。有的時候，或許可以考慮機器翻譯加人工干預，也就是對其中個別的地方，手工做出處理，例如像 Google Translate 那樣，點擊譯文中的某個詞語，然後選擇你認為更合適的其它譯法，或者輸入自己的譯法。這些修訂操作，也可以記錄並收集起來，慢慢形成知識庫。然後……或許對解決詞彙歧義有所幫助？

[nobodxbodon]

刚发现的使用中文命名标识符(包括Python, 前端模板, 数据库等等)的2018年Django系列视频教程!

• Django 2 之登录注册(2018.6.18 更新)
  

• Django 2 零基础 - 待办清单网站 (2018.6.13 更新)
  
  

• Django 2 零基础 - 购物网站制作 (2018.6.11 更新)
  
  

[nobodxbodon]

日本编程书籍《我的第一本编程书》（原书 2016 年7月出版）例程中，借助作者自制的语言工具，代码的所有关键字和标识符都使用了日文。中译版将它们都翻译为了中文。

从中借鉴，看中文例程如何扬长避短：
标识符（一）
抽象层次（二）