如何寫出讓別人好維護合修改的程式?
如題，debug又難又花時間，debug自己的程式還好，幫別人debug而看不懂別人的思維，就會花更多時間@@，我想請問的是如何寫出"讓人看得輕鬆且好維護的"程式!?<div></div> 本帖最後由 kwj 於 2014-8-24 09:46 PM 編輯
最基本的就是多寫註解。
會看不懂別人寫的程式碼，就是因為程式碼裡的註解不夠明確，所以看不出來那段程式碼想要幹嘛。
另外要注意的是，寫註解需要的是描述程式碼的概念，而不是描述程式碼本身
例如
// 當 a 小於 60 時執行
if( a < 60) {
....
}
這樣的註解一點用處都沒有，誰都知道 if( a < 60) 是什麼意思，不需要在註解上重複寫一次
真正需要寫的是例如「學生的分數低於 60 分時，視為不及格，要把學生標註為需補考的對象」
也就是要描述的是程式碼真正想做的目的，而不是用文字的方法又重述一次程式碼的內容。
光是寫註解這件事，就有很多書在討論，另外也有很多像是命名之類的議題
建議樓主可以看看「clean code」這本書，主旨在討論一些讓程式碼簡潔易讀的建議...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> kwj 發表於 2014-8-24 08:07 PM static/image/common/back.gif
最基本的就是多寫註解。
會看不懂別人寫的程式碼，就是因為程式碼裡的註解不夠明確，所以看不出來那段程式 ...
謝謝你建議的書 ~~ 我會多寫註解，只是在維修別人程式時，別人不打註解，而且人又不在，我真的是頭很大哈哈~...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> kwj 發表於 2014-8-24 08:07 PM static/image/common/back.gif
最基本的就是多寫註解。
會看不懂別人寫的程式碼，就是因為程式碼裡的註解不夠明確，所以看不出來那段程式 ...
其實 clean code 裏認爲註解應該是越少越好
因爲高階語言的目的就是要讓人看懂
而註解用的越多代表你程式越沒有達成這個目的
首先應該考慮的是 rewrite 你的程式，而非加註解...
像是 function/class 並非單一功能性、取名太模糊之類的
我記得書裏有特別開一個篇章講 coment XD
雖然我覺得 clean code 裏有時候太極端了啦
但是基本上有些程式語言也是保持著類似的理念
像是 python 的 explicit is better than implicit
...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> 本帖最後由 kwj 於 2014-8-25 10:01 AM 編輯
sh7162c 發表於 2014-8-25 06:15 AM static/image/common/back.gif
其實 clean code 裏認爲註解應該是越少越好
因爲高階語言的目的就是要讓人看懂
而註解用的越多代表你程式 ...
所以開頭才說 "最基本的"，首先要先開始寫註解，然後才能慢慢理解其他動作的意義（包括不寫註解的意義）
畢竟註解是所有工作裡面最容易聽到、也最不容易造成反彈的方式。
至於中間過程發生什麼事，應該讓樓主自行去體會，而不是一開始就告訴他結果。
會這樣回覆，是因為我個人認為不寫註解之前有些前置工作要做
而這些前置工作，對於還不夠成熟的程式設計師來說是非常困難的
如果在樓主還沒有任何嘗試之前，就直接朝不寫註解的方向前進，走歪的機會應該蠻高的。
clean code 教派到底要不要完全尊崇，那也是見仁見智
畢竟 clean code 也只是眾多 coding style 裡的其中一種。
書中開頭也寫了，讀者可以不要遵守他們的規則，但應該先了解他們的規則的用意，然後再自己去評斷
因此上頭在回文時，沒有特別提到 clean code 裡面描述的細節
那些細節應該慢慢讓樓主自行去研讀、思考，然後再決定自己的 coding style。
前面的回覆沒有說明清楚很抱歉。...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div><br><br><br><br><br><div></div> 本帖最後由 chevylin0802 於 2014-8-25 11:13 AM 編輯
幾個事項是需要注意的
應有的註解最好要有
但是盡可能別放太多註解
但沒有必要在每一行加註解
註解的內容主要是闡述設計理念
另一個問題是排版
好的排版有助於清楚的知道每一個區塊
現在的程式設計師都很不注重排版
可是那對於debug來說是很麻煩的事情
但是排版這個部份也盡可能別使用tab
因為不同的文字編輯器或IDE環境對於tab的判讀不一樣
所以以你自己的文字編輯器編出來的時候或許已經完成排版了
到了別人手上可能變成是亂的
因此寧可使用space也不要太倚靠tab
即使感覺上會麻煩了許多
第三個問題是像是JAVA, C, C++...等
很多語言都使用 {, }
這種情形之下
那麼巢狀階層太多的時候維護的困難度就會增高
如何以更簡化的邏輯來降低巢狀階層也很重要
統一化格式
非常重要
最後一點是
如果是JAVA的程式
一定要做出可以讓javadoc編出api文件檔
二十年前的方式確實不適合今日
以前所謂的三圖四冊文件
現在坦白講沒有人有那個美國時間看
最後
就是要講到程式架構的問題了
好的程式架構與差的程式架構
差異性會相當相當的大
好的程式架構易於維護
差的程式架構則否
有時候還可能為了一個差的程式架構打掉重寫重練
這一點千萬要弄清楚
千萬別只是就現有規格做
整體考量一定要考量到未來的部份
...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> kwj 發表於 2014-8-25 09:52 AM static/image/common/back.gif
所以開頭才說 "最基本的"，首先要先開始寫註解，然後才能慢慢理解其他動作的意義（包括不寫註解的意義）
...
我記得 Clean Code 的作者是認爲要寫出好的註解甚至比寫出能自我描述的程式還難
記得他舉例像是程式改版註解卻沒有改(Linux Documentation 躺著中槍XD)
還有註解往往無法描述精確造成誤解，畢竟程式只會依照你寫的跑，不會依照你想得/說的跑XD
至少我認爲這點好像和你所說的寫註解是比較入門的方式是相反地啦
不過其實很多老師和前輩也都會說一定要把每個地方用註解描述清楚
纔不會回來連自己都看不懂之類的...
當初讀到這段的確讓我有滿多的新體悟
不過到底新手應該怎麼入門...我想其實歪路都不會少走啦XD
就像讀再多程式架構的書，如果沒有累計足夠的 refactoring 經驗
想要一開始就規劃出多有彈性的架構是不太可能的
這種工程議題上能看得多遠還是想當程度依賴於經驗...<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> 軟體這個東西 就一直在 trade off
至少寫的程式碼 和 註解, 文件 在兩星期後 你自己還能看得懂,如果 連你自己2星期後 都看不懂 那就該改了..........
先熟悉 你團隊的開發流程 規範 照人家的走,熟悉了 也有話語權 有不好的地方再來談談怎麼改. 別拿著軟體工程 或 Design pattern 的書..... 就要大家跟著改........
導入一套流程 制度 都要有成本的概念 也要注意到 它無形中也可能對新進者築起一道門檻........<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div> variable naming 必須有意義,maintain 的人才有辦法了解城市的意義~~ 我覺得最主要就是每個行為、函數、function都要meaningful
而當你覺得別人看到這段不知道你在幹嘛的時候，
除了寫註解外，另開一個function代表整段在幹嘛也可行
因為debug時，通常看到一個function 名稱我知道它在幹嘛，in/out 也符合陳述
就不會鑽進去仔細看每個步驟
有些寫得好的code甚至不太需要註解
當然，這是在自己寫code的時候的自我要求....
當debug到很瞎的作者時，就只能自立自強了....
本人就是非常衰小，
常常要修那種將近10年前code而且寫的人都不知道離職幾年的那種
裡面還夾帶了一堆現在都已經被淘汰死光光的lib....
除了幹譙還是幹譙.......<div class='locked'><em>瀏覽完整內容，請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div><br><br><br><br><br><div></div> variable,Function名稱不要亂取
每個Function前面寫註解,盡量精簡
不要故意用一些奇奇怪怪的寫法
Design patent的書可以多參考 現在的程式 實在 太巨大了... 我 個人 覺得 還是 用 註解 比較恰當...
畢竟 每個人的 思維 都 很不一樣... 以前是會希望別人看懂我寫什麼啦
現在已經放棄了
誰寫的誰負責
就這樣
這還要看工程師的頭是怎麼領導的
案子一急哪管的了那麼多
質與量難以兼顧 註解比較能夠讓大眾了解...
不然為了效率或簡潔...
有時候要追好幾層才了解...
不過...很多演算法就算註解也不一定看得懂.. 我覺得真的真的一定要加註解...
而且最好在每一個Function前面都要寫上註解
然後不要覺得維護的人是天才，看你一行註解就可以懂你整個Function在幹嘛
最好的是在你覺得關鍵的地方寫得仔細一點，然後寫一點小筆記在一份文件裡
最好...不然真的下一個接手的人真的會看到死...
((一個接下一整個ROR project且之前沒寫過的人的小意見 PS:寫的這個人再整個project只有三行註解==<br><br><br><br><br><div></div>