軟體開發之文件有感

  1. 工程人都不喜歡寫文件。這是真的,喜歡寫文件能寫文件的可能就不會走這條路。
  2. 文件是為了承先啟後,如果我們想一輩子做底層的程式設計師,當然功能做好等下班就好。
  3. 文件寫到夠用,看得懂就好。使用一些共同編輯的工具減少文件的維護問題(譬如說註解或wiki)。
  4. 不要硬逼工程人員達到不可能的標準,反而要逐步教育,一次只要求多一點,反彈就會比較小。
  5. 從源頭開始,從程式碼註解開始,寫程式碼的人最熟程式碼,讓他們在習慣的地方寫文件。
  6. 使用自動化的軟體建立文件,教育程式人員寫Doxygen的註解,減少撰寫無謂的文件的時間(類別,成員,定義等等)。
  7. 從進程式碼(commit)的註記開始,確保每次的改動都知道為了什麼。也就是有些人提倡寫User Story,一口氣沒辦法從無到有把完整的文件建出來,那就從每次改程式發生了什麼事情開始,一次只寫一點,累積這些軌跡,一樣有他的效果。
  8. 先寫文件,再開發。讓程式人員在還沒真正寫程式之前把規格,問題,以及要做的事情都搞清楚。避免過度設計或做多餘的介面與功能。
  9. 開發後,寫文件。補充介面的註解,為什麼要寫這個功能,撰寫Tutorial或Example。讓其他人知道到底這個功能:為什麼,是什麼,該怎麼用。
  10. 找助理來幫忙寫註解/文件,讓程式人員沒有藉口。
  11. 文件是為了溝通,用嘴巴講都很簡單,用嘴巴講都說就是這樣沒錯,一寫下來清清楚楚白紙黑字賴不掉,馬上就改口說其實我的意思不是這樣。
  12. 文件從寫完的那一刻開始就過時了,但是一個過時的文件都比沒有文件來的好。
廣告

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com Logo

您的留言將使用 WordPress.com 帳號。 登出 / 變更 )

Twitter picture

您的留言將使用 Twitter 帳號。 登出 / 變更 )

Facebook照片

您的留言將使用 Facebook 帳號。 登出 / 變更 )

Google+ photo

您的留言將使用 Google+ 帳號。 登出 / 變更 )

連結到 %s