Re: [請益] 寫註解到底是不是好習慣消失

看板Soft_Job (軟體人)作者taliao時間7年前 (2018/12/28 20:47)推噓0(0推 0噓 2→)

留言2則, 1人參與討論串6/24 (看更多)

※ 引述《sec5566 (sec)》之銘言： : 以前上課跟書本都提到寫註解， : 但是我看資深同事還有接手的程式碼， : 都沒有註解，只有我在寫， : 還被主管念過寫註解沒必要， : 命名好就夠了， : 是我觀念落伍了嗎？ : ----- : Sent from JPTT on my Sony H4331. 這是個封閉式問題，意即非黑即白。理想的情境：程式碼的命名 "都" 能被清楚的解讀。理想的情境：記者寫的內容是客觀的實際的狀況是：理想通常支離破碎 XDD 實際的情境：程式碼的命名產生的過程，因為有： - 時程壓力 - 需求不清楚 - 業務亂喊時程 - 貴司跑敏捷, 所以不重要 - 菜鳥功力不夠 - 終於可以盡心寫程式, 但窗外在跨年放煙火 - 前人已經作古 - PM 是正妹 (誤) - 辦公室沒酒喝 .... - 重構 2.0 還沒中文版, 所以不會重構恩，我只有寫 "命名" 這件事情。 --- 回到正題，身為一個專業的 Developer，如果擔心程式邏輯寫完之後，後續接手的人無法很快理解用意，或者沒有具體的參考文件，像是： - Sequence Diagram - Class Diagram - User Story - Issue Number for Bug or Defect. 建議，在你時間允許的前提，該說明的要說明。註解的目的，是第一時間提醒看扣的人，知道應該知道的、應該注意的。然後應該知道的事情，不是要去 VSC 找才能知道。如果接手的人無法在第一時間意會到該知道的事情，或者他沒有很瞭解商業邏輯，後許只會死得莫名其妙，然後就會上來這裡 po 文問為什麼沒有好好讀註解。另外要說的是，寫扣的人，要養成閱讀的習慣，否則，再清楚的註解都只是裝飾品。 --- by the way, 這問題可以延伸成： - 怎樣扣不需要寫註解？ - 怎樣寫出好的註解？有哪些不錯的 OSS 範例？ - 除了註解，大家都怎麼用其他文件輔助？工具？ - 如何讓團隊養成寫註解的習慣？ -- ※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 36.231.116.212 ※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1546001229.A.CBC.html