---
title: 失憶症限定，開發手冊製作
slideOptions:
transition: slide
tags: 簡報
---
## 失憶症限定，開發手冊製作
### 以Swift為例
---
##### Present by: 游諭
To this keynote.
---
| Key | value |
| -------- | -------- |
| name | 游諭 |
|nickName | "Yu" |
|now|Craftsman|
|reading|Git､命名原則|
---
參考資料：
1. cc2e: 第32章 自我文件化程式碼
2. 易讀程式碼之美學
3. Apple - Markup format
4. jazzy
5. Medium
note:
軟體開發實務指南 36頁(779~815)
---
## Agenda
- 文件
- 註解
- MarkDown
- Jazzy
---
## 文件
- <span style="color:orange">文件</span>
- 註解
- MarkDown
- Jazzy
----
> 好的文件說明是程式設計師放在程式裡面、展現其專業成就的標誌。
> 『軟體開發實務指南』
----
----
什麼是好的文件說明？🤫
----
程式碼自我檢查
1. 類別名稱有意義嗎？能顯示其核心意圖嗎？
2. 每個子程式名稱都能準確指示其確切做些什麼嗎？
3. 變數名稱有意義嗎？
4. 迴圈變數能提供更多資訊嗎？而不是`i`, `j`, `k`?
5. 程式術語是否盡可能用問題領域術語，而不是ＣＳ術語？
---
## 註解
- 文件
- <span style="color:yellow">註解</span>
- MarkDown
- Jazzy
----
### 程式碼文件
> 註解還是不註解？to be, or not to be
----
### 反對寫註解
- 我已經有夠多的程式碼要看了，何必再去讀一大堆註解？
- 註解沒什麼用，他只不過是用更囉唆的方式又重複寫一遍程式碼...
- 沒人更新程式碼的註解
- 當精力其中在程式碼時，不該分心去寫註解。
----
### 支持寫註解
- 被追問“你這段程式碼到底在寫什麼”的折磨。
- 寫註解不是浪費時間，而是給自己一個工作上的指標。
- Pseudo code 型態的註解 [wiki](https://zh.wikipedia.org/wiki/伪代码)
----
### 高效率註解
1. 註解風格
2. 虛擬碼設計
3. 註解技術
----
1. 註解風格 - 難以維護的風格
``` c
不易編輯
/***********************************／
/* ｃｌａｓｓ： 範例類別 */
/* *／
/*作為簡報範例使用 *／
/***********************************／
//ｃｌａｓｓ： 範例類別
//
//作為簡報範例使用
```
----
1. 註解風格 - 簡單維護的風格
```c
/*********************************
* ｃｌａｓｓ： 範例類別
*
* 作為簡報範例使用
*********************************／
```
----
2. 虛擬碼設計 - 1A2B Pseudo code
```swift
簡易版本
while A != 4
A= 0, B = 0
if isvalid(input)
for i in 0...3 && j in 0...3
if answer[i] == input[j]
if i == j A++;
if i != j B++;
進階版本
當不是4A0B
重設為0A0B
如果輸入合法
遍歷正確答案與輸入答案
當出現字元相等時:同格則A+1，不同格則B+1
```
----
- 假如在寫程式碼之前以註解先勾勒出程式碼，完成程式碼之日，也是註解寫好之時。
- 再填入低層次的程式碼之前，就以寫出高層次的虛擬碼，因此可以獲得所以設計方面的好處。
- 當發生難以設計邏輯時，使用虛擬碼整理思路，編碼會更容易，註解也自然而然做好了。
----
3. 註解技術 - Know How
1. 行尾註解
2. Why > How
3. 程式碼本身的註解功能 a.k.a. 命名
4. 子程式的介面假設
5. 標註類別､檔案､APP
6. IEEE ISO 軟體開發標準
```
///建立一個新帳號
if accountType == AccountType.NewAccount{
...
}
```
note:
1. 宣告輸入輸出資料時使用
```swift
func demoFunc(
data:String //需要處理的資料
for:Int //資料處理的參考
)->String //回傳的資料是如何如何＊＆＾％
```
2. Why > how
3. 程式碼本身的註解功能 a.k.a. 命名
4. 子程式的介面假設
1. 斷言前制條件與後製條件 cc2e ch8.2
2. 子程式的侷限性
3. 說明子程式的全域效果
4. 紀錄演算法資料來源
5. 使用ＭＤ註解程式各部分
---
## Xcode mark down
- 文件
- 註解
- <span style="color:green">MarkDown</span>
- Jazzy
----
## Markdown v.s. Markup
----
1. Description
1. Parameters
1. Throws
1. Returns
----
### 單行或是區域註解區別
```
Single Line
/// Quick help Syntax
//: Playground Syntax
Block Comment
/** */ Quick help Syntax
/*: */ Playground Syntax
```
----
Italics, Bold
```
**bold** or *italic*
__bold__ or _italic_
```
----
lazy like me: `cmd`+`opt`+`/`
note:
Attention
**Inserting Callouts**:
* Author
* Authors
* Bug
* Complexity
* Copyright
* Custom Callout
* Date
* Example
* Experiment
* Important
* Invariant
* Note
* Pre-condition
* Post-condition
* Remark
* Requires
* See Also
* Since
* Version
* Warning
---
## Xcode 插件
- 文件
- 註解
- MarkDown
- <span style="color:orange">Jazzy</span>
----
----
`$> jazzy --min-acl internal`
note:
```
MIN ACL
Config file: min_acl
Command line: --min-acl [private | fileprivate | internal | public | open]
minimum access control level to document
Default: public
```
---
## Review today:
- <span style="color:orange">文件</span>
- <span style="color:yellow">註解</span>
- <span style="color:green">MarkDown</span>
- <span style="color:orange">Jazzy</span>
----
----
## 避免寫作抗拒
- 原始碼應當含有程式大部分的關鍵資訊。
- 註解應說出程式碼無法說出的事情，如概述或用意。
- 差勁的文件/註解只會浪費時間，好的註解才有價值。
- 有些註解風格需要重複性勞動，應改用易於維護的註解風格。
note:
好的程式碼本身就是最好的說明。
---
## before Q&A
找人共讀/筆：易讀程式碼之美學
----
## Q&A
----
### Thank you
spoiler alert: Pseudo code
note:
Source:
[Apple Developer - Markup format](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1)
[jazzy - Github](https://github.com/realm/jazzy)
[Easy Documentation for your Swift project using Jazzy](https://medium.com/@arpit.cor/easy-documentation-for-your-swift-project-using-jazzy-9117f6a8709a)
```
$> jazzy -h config
OUTPUT
Config file: output
Command line: -o, --output FOLDER
Folder to output the HTML docs to
Default: docs
SDK
Config file: sdk
Command line: --sdk [iphone|watch|appletv][os|simulator]|macosx
The SDK for which your code should be built.
Default: macosx
HIDE DECLARATIONS
Config file: hide_declarations
Command line: --hide-declarations [objc|swift]
Hide declarations in the specified language. Given that generating Swift docs only generates Swift declarations, this is only really useful to display just the Swift declarations & names when generating docs for an Objective-C framework.
CONFIG FILE
Config file: config
Command line: --config PATH
Configuration file (.yaml or .json)
Default: .jazzy.yaml in source directory or ancestor
XCODEBUILD ARGUMENTS
Config file: xcodebuild_arguments
Command line: -x, --xcodebuild-arguments arg1,arg2,…argN
Arguments to forward to xcodebuild
Default: []
SOURCEKITTEN SOURCEFILE
Config file: sourcekitten_sourcefile
Command line: -s, --sourcekitten-sourcefile FILEPATH
File generated from sourcekitten output to parse
EXCLUDED FILES
Config file: exclude
Command line: -e, --exclude filepath1,filepath2,…filepathN
Source file pathnames to be excluded from documentation. Supports wildcards.
Default: []
AUTHOR NAME
Config file: author
Command line: -a, --author AUTHOR_NAME
Name of author to attribute in docs (e.g. Realm)
AUTHOR URL
Config file: author_url
Command line: -u, --author_url URL
Author URL of this project (e.g. https://realm.io)
VERSION
Config file: module_version
Command line: --module-version VERSION
module version. will be used when generating docset
Default: 1.0
README PATH
Config file: readme
Command line: --readme FILEPATH
The path to a markdown README file
GITHUB URL
Config file: github_url
Command line: -g, --github_url URL
GitHub URL of this project (e.g. https://github.com/realm/realm-cocoa)
GITHUB FILE PREFIX
Config file: github_file_prefix
Command line: --github-file-prefix PREFIX
GitHub URL file prefix of this project (e.g. https://github.com/realm/realm-cocoa/tree/v0.87.1)
MIN ACL
Config file: min_acl
Command line: --min-acl [private | fileprivate | internal | public | open]
minimum access control level to document
Default: public
THEME DIRECTORY
Config file: theme
Command line: --theme [apple | fullwidth | jony | DIRPATH]
Which theme to use. Specify either 'apple' (default), one of the other built-in theme names, or the path to your mustache templates and other assets for a custom theme.
Default: apple
```
```
$> jazzy -h
```
Sign in with Wallet
Connect another wallet