文分享自華為云社區《代碼的安全檢視-云社區-華為云》，作者：Uncle_Tom。
熵的概念最早起源于物理學，用于度量一個熱力學系統的無序程度。熱力學第二定律，又稱“熵增定律”，表明了在自然過程中，一個孤立的系統總是從最初的集中、有序的排列狀態，趨向于分散、混亂和無序；當熵達到最大時，系統就會處于一種靜寂狀態。
通俗的講：系統的熵增過程，就是由原始到死亡的過程。“熵” 是 “活躍” 的反義詞，代表負能量。
物質總是向著熵增演化：
自然界除了自然風化的作用，也少不了人為的因素。
1982年3月，詹姆士·威爾遜（James Q. Wilson）及喬治·凱林（George L. Kelling）發表一篇題為《Broken Windows》的文檔，提出了犯罪學的一個理論 – 破窗效應。此理論認為環境中的不良現象如果被放任存在，會誘使人們仿效，甚至變本加厲。
一個房子如果窗戶破了，沒人去修補，隔不久，其他的窗戶也可能莫名奇妙地被人打破。環境可以對一個人產生強烈的暗示性和誘導性。
這個理論從另一個側面說明了對一個系統需要及時維護，以減少人為的熵增現象。古人云：勿以惡小而為之，勿以善小而不為。
對于我們創造的代碼，也是一樣，大家制定了編碼規范，以期盡量減緩熵增，從而達到延長軟件的生命周期。
代碼檢視一直被認為是提高代碼質量的重要手段，同時也是發現潛在問題的重要途經。代碼檢視有以下重要意義。
代碼檢視是確保代碼質量的重要環節，它有助于開發人員編寫易于理解的代碼。
微軟和谷歌等公司在代碼檢視中積累了豐富的經驗，強調了代碼的可讀性對于團隊協作的重要性。當代碼清晰、結構良好時，其他開發人員能夠更快地理解代碼的功能和目的，從而提高團隊的整體效率。此外，良好的代碼可讀性也有助于新成員快速融入團隊，因為他們可以更容易地理解現有的代碼庫。
史蒂夫·邁克康奈爾的《代碼大全》，被福布斯技術委員會（Forbes Technology Council）譽為“有史以來最好的軟件開發基礎書” 。
《代碼大全》書中提到了提高代碼可讀性的多種方法，包括使用有意義的變量名、避免嵌套過深的語句、使用函數和模塊、面向對象編程、避免重復代碼、使用設計模式、編寫注釋和文檔、使用調試工具、進行代碼審查、學習和使用更高級的編程語言和技術等等。
軟件工程的核心就是管理復雜度。規模更大的項目，如果不對復雜性做出限制，那么項目的每個步驟都可能崩潰失控。以往，無數大型項目都在砸下巨量資金后失敗了，原因就是其過于復雜，已經無人能理解究竟發生了什么，就如同過于龐大的巨獸被自身重量所壓垮。
復雜性其實貫穿于軟件開發的各個階段，復雜性在編碼過程中，如果底層代碼的質量不好，超大規模系統也可能就由此崩潰。所以必須立足底層，立足細節抓代碼質量，關注每個語句、例程和類，步步為營，以此為基礎才能擴大規模，同時繼續保持代碼質量，即在設計和架構層級控制復雜性，對復雜性控制要廣泛而深入地體現在軟件開發的各個階段。
唐納德·克努特（Donald Knuth），他在編程界被廣泛認為是“計算機程序設計藝術”的創始人之一。克努特曾說過：“Programs are meant to be read by humans and only incidentally for computers to execute.” 這句話強調了代碼的可讀性對于人類的重要性，意味著代碼首先應該是為了讓人理解而編寫的，而機器執行只是其次。
這是《A practical guide to object-oriented metrics》中的一個統計圖，作者分析了一個數據庫系統，黃色柱狀體是缺陷的百分比，紅色柱狀體是代碼的比例，橫坐標標識了不同圈復雜度。最左邊代碼圈復雜度在0-5的時候，代碼量占了總量的40%，缺陷數占了10%，而最右邊圈復雜度為15+， 代碼量占比10%，但缺陷數量占了缺陷總數的40%+。從左向右的可以看到代碼的圈復雜度越高，缺陷的比例也越高。
通常我們不能一次性編寫出完全滿足需求的代碼；或者需求在不斷的變化；維護代碼的人往往不是原始開發的人員，這些都要求我們編寫的代碼是可被另一個人所理解和修改的。
代碼檢視是維護編碼規范的關鍵機制。
代碼的可讀性、可維護性需要具體的規約來保持。我們往往通過編碼規范來維護和保持代碼的易于理解和避免一些常見的錯誤（或被稱為最佳實踐）。因此各大公司都有了自己的編碼規范，比如我們熟知的google的編碼規范。同時行業也為了維護行業的統一性，也給出了行業的編碼規范，像MISRA C 2012、AUTOSAR C++14 等等。更多的關于規范的信息，可參考《一圖看懂軟件缺陷檢查涉及的內容-云社區-華為云》。
通過代碼檢視，可以確保所有代碼都遵循了既定的編碼標準和最佳實踐。這有助于保持代碼庫的一致性，減少由于風格不一致或不遵循規范導致的維護問題。
目前的編碼規范通常會包含兩部分：
一致的代碼風格。整個項目中保持一致的編碼風格，可以減少開發者在閱讀不同部分代碼時的認知負擔，因為他們不需要適應不同的風格。這包括：
編碼實踐
每個編程語言都有自己的特點和特定的規約，很多地方往往被開發人員忽略從而埋下潛在的風險。
這部分通常包括：
規范的維護還有助于提高代碼的可維護性和可擴展性，因為所有開發人員都遵循相同的規則和模式。
目前規范的很多部分都能夠被靜態分析工具檢測到，甚至自動修復。這些工具的告警也會在代碼檢視的時候得到確認，是否是誤報，還是確實需要修改。對被確認誤報的部分會反饋給工具團隊，進一步的修正檢查工具，起到對工具反饋的作用。
此外，代碼檢視還可以作為規范更新和改進的反饋機制，團隊可以根據實際開發經驗，不斷調整和完善編碼規范，以適應不斷變化的開發需求和技術進步。
代碼檢視為開發人員提供了學習和教育的機會。
在微軟和谷歌等公司，代碼檢視被視為一種學習和知識共享的平臺。通過檢視他人的代碼，開發人員可以學習到新的編程技巧、設計模式和最佳實踐。
同時，代碼的作者也可以從其他開發人員的反饋中學習，了解自己的代碼在哪些方面可以改進，這對于個人技能的提升非常有幫助。代碼檢視還可以作為一種教育工具，幫助新員工快速了解公司的代碼風格和開發流程。通過參與代碼檢視，新員工可以更快地融入團隊，提高自己的開發能力。
代碼檢視還可以揭示潛在的設計問題，促進團隊成員之間的知識共享，增強團隊的凝聚力。通過代碼檢視，開發人員能夠從同事那里得到反饋，學習如何寫出更清晰、更高效的代碼，這對于個人技術成長和團隊協作都是有益的。
代碼檢視在把關和事故預防方面起著至關重要的作用。
代碼檢視除了確保代碼的質量，還可以防止潛在的錯誤和缺陷進入生產環境。代碼檢視可以幫助開發人員發現代碼中的錯誤，包括邏輯錯誤、性能問題、安全漏洞等，從而在代碼發布前進行修復。這不僅可以減少生產環境中的問題，還可以降低維護成本和風險。
雖然靜態分析工具在缺陷檢查上承擔了越來越重要的防護作用，可畢竟檢查能力在開發框架和第三方調用上，需要很多的人為配置才能使分析工具在很大程度上識別框架上潛在的調用關系和第三方函數的行為。目前靜態分析工具在這方面都還有很大的欠缺，這將導致很多的漏報。所以代碼檢視在防范代碼缺陷上還是不可缺少的檢查環節。
隨著外部的惡意攻擊的增加，缺陷的發現和漏報的矛盾也越發的突出。
檢查工具畢竟只是輔助，還是需要開發人員建立安全防范意識，寫出沒有缺陷的代碼，這個才是安全預防的治本方法。通過代碼檢視，團隊可以建立起一種預防文化，不斷提高代碼質量，減少事故發生的概率。
將代碼評審用作團隊建設活動，培養對發現缺陷的積極態度。為所有團隊成員提供糾正壞習慣、學習新技巧和擴展能力的機會。
尊重和鼓勵、禮貌和專業精神；
一次代碼提交不易過大
SmartBear對思科系統編程團隊的一項研究表明，開發人員一次審查的代碼行數不應超過200到400行（LOC）。大腦一次只能有效地處理這么多信息;超過 400 LOC，發現缺陷的能力會減弱。
在實踐中，在 60 到 90 分鐘內對 200-400 LOC 進行審查應該會產生 70-90% 的缺陷發現。因此，如果代碼中存在 10 個缺陷，那么正確進行的審查會發現其中的 7 到 9 個。
SmartBear 研究表明，以每小時 500 LOC 的速度快速下降，缺陷密度顯著下降。在有限的時間內以合理的速度進行合理數量的代碼審查，從而產生最有效的代碼審查。
在代碼提交檢視前還需要完成以下工作：
代碼審核人員在審核過程中主要的審核內容包括：
結合業界的主要安全編碼問題，總結了代碼檢視的安全檢查清單如下。
注：下面問題涉及的 CWE 有的是類別，需要包括下面的子CWE編號。
[ ] 是否有外部輸入，例如：http request, 表單輸入、配置文件、數據庫讀？
防范的問題：
[ ] 是否有 SQL 操作？
防范的問題：
[ ] 是否有命令操作？
防范的問題：
[ ] 是否有文件操作？
防范的問題：
[ ] 是否有反射操作？
防范的問題：
[ ] 是否有頁面輸出操作？
防范的問題：
[ ] 是否有日志輸出操作？
防范的問題：
[ ] 是否有數據傳輸操作？
防范的問題：
[ ] 是否有加解密操作？
防范的問題：
[ ] 是否有權限驗證、設置、變更操作？
防范的問題：
關注#華為云開發者聯盟# 點擊下方，第一時間了解華為云新鮮技術~
華為云博客_大數據博客_AI博客_云計算博客_開發者中心-華為云
文檔是我們工作中最基礎的一部分，但是這些產出物真的合格嗎？如果我們想提升文檔能力，可以采用哪些“拿來即用”的簡單方法？本文分享了一些基礎的規范和注意事項，希望能對你有點幫助。
早在今年七月份，就想給同事培訓一下關于寫文檔中需要注意的基礎要求、基礎規范。但是因為種種原因一直拖延到現在，我決定把這些內容整理成文字分享出來，希望每位同行都能夠重視文檔的基本規范，不要因為一時的疏忽而造成不必要的負面影響。
文檔本身是產品經理日常工作中最基礎的一部分，我們幾乎每天都在寫文檔，但是這些產出物真的合格嗎？如果我們想提升文檔能力，可以采用哪些“拿來即用”的簡單方法？
今天我便以自己這些年在寫文檔中（以word為主）踩過的坑，以及在工作中總結出的技巧逐一介紹。
全文概覽：
文章不短，可以先收藏哈~
提升意識，是做好一件事的前提條件。
我發現很多文檔寫的不合格，甚至比較爛的同學，在重視程度上就很差。所以最近兩年我在新同事入職培訓過程中，第一要務就是提高大家對文檔產出的重要意識，并通過前期工作的仔細檢查篩選出常見錯誤，后期自己再寫的時候才能真的注意這些問題。
幸運的是通過一年多的努力，還是有所成效。
對于我們日常產出的文檔來說，無論是需求說明書、產品手冊、產品介紹、甚至于一個普通的word匯報材料，或者項目進程中、驗收過程中的各項產出物，或者售前過程中的諸多物料，都能客觀反映出一個人、一個團隊、甚至于一家公司的專業性。
所以，如果我們真的只把這些文檔當做團隊內部的“應付材料”，或者覺得反正這么多字，也沒人細看而長期沒有形成好的規范習慣，那后續會踩到的坑一定不會比我少。
因此，我簡單總結四點文檔規范的重要性供大家參考，希望能引起我們真正的重視：
明確重要性之后，我們便可以正式介紹今天的主題：基礎規范要求
因為不同的行業，不同的團隊，不同文檔用途，其中的內容、格式、結構等等都會有非常大的差異。所以本文不會在這些“變量”中過多介紹，而是從各類文檔都要遵循的基礎規范來進行說明。
這方面大多數產品同行應該都會注意，但很多時候文檔寫多了，我們也會變得“麻木”而忽略一些細節。而其他崗位的同事很多就不太注意文檔格式的規范性，最終的交付物讓人“一言難盡”。
格式規范性主要包含字體、段落標題、段內標題、圖片、目錄這幾類內容。
字體最關鍵是需要全文統一，我們可以按“正文字體”、“小標題字體”、“表格內字體”、“補充說明字體”、“重點突出字體”來分類，并保證每個類別的全文字體一致。
表格內的字體還要考慮字體大小是否會讓表格排序“失真”或“凌亂”，表格的首行標題建議加粗、居中。章節的各級標題一定要使用格式刷來統一維護。
很多文檔不同的段落字體大小、樣式都會有些偏差，究其原因還是作者沒有檢查的意識，也沒有在完成復制粘貼后順手用格式刷統一的習慣。
各級標題在用格式刷統一的過程中，非常容易出現一些小錯誤。
比如級別錯誤，下圖便是將四級標題，誤刷成三級標題。
比如沒有重新開始編號，下圖顯然是將規則復制粘貼過來之后，沒有重新編號。
一個文檔中段落內的小標題也盡量采用一種格式，比如選擇使用（1）（2）（3），就不要再使用①②③，除非在文檔中有多處不同級別的排序需求再考慮多種小標題樣式。
文檔中的圖片要居中，如果某個章節有多張圖片連續，則需要給每個圖片附上文字說明。
而且圖片的大小也需要微調，尤其是一些圖片復制進去之后很大、很模糊，此時把圖片縮小成盡量全文統一的大小則顯得很有必要。
尤其是一些移動端截圖，復制到文檔之后可能會“又細又長”，這時我們一定要隨手調整大小。
目錄記得及時更新，我們經常遇到內容修改之后沒有更新目錄直接提交的情況。
也要記得把目錄的字體、間距調整到適當，因為很多默認的目錄格式說實話，挺丑的。
以上這些細節，都是文檔的格式規范要求，每一條單獨來看可能都知道要這樣做，或者也很簡單覺得可以做到，但當這些問題匯集到同一個文檔時，就是“閱讀者的災難伊始”。
關于文檔的內容，因為不同的行業和用途有不同的內容要求，本文側重點不在于內容如何整理，而是無論哪種內容，我們都需要檢查、規避的常見問題。
在智能輸入法普及的今天，我們日常的文字交流中充滿了錯別字，而這些錯別字一旦在產品工作者的產出物中出現，會非常影響“印象分”，同時也會被質疑此人的細心、認真程度。
大家也都知道出現錯別字不好，但苦于難以察覺，但這并不是我們任由錯別字存在的理由。所以對于錯別字，我有以下幾點建議：
1）換一個相對智能的輸入法
畢竟一個好的輸入法能夠記住我們常用的專業術語，能夠在拼寫錯誤時給出智能提示，操作系統默認的輸入法很難達到這個效果。
我曾經發現一位經常打錯別字的小伙伴，就是一直在使用mac的默認輸入法，換了搜狗之后能降低大約60%的錯字情況。
錯別字很煩銀，比如當你讀到這段話的時候，能否一言就看出短短幾十個字里飽含著多少問題呢？我在看新同事寫的文檔時，關注的第一要素就是有么有矬子和語句不通順的標大。
2）在日常生活中多注意
平時打字聊天的時候就養成不打錯字的習慣，發出去的內容自己再掃一眼，如果出現了錯別字及時改正，我認為這是一件很基礎的事情。
但是很多人都不在意，甚至被人多次指出之后也只是呵呵一笑，找個寬慰自己的理由，這些人一定寫不出合格的產品文檔。
3）團隊內可采取一些獎懲措施
比如在關鍵文檔中出現錯別字之后，在團隊內部發紅包，或者當你看到其他同學的文檔有錯別字時及時提醒。
總之一定要采取一些措施，讓大家重視起來，養成日常檢查的習慣，漸漸地錯別字一定會越來越少。
4）自己一定要通讀幾遍
一個大段落寫完之后，一定要重新讀至少一遍，一方面檢查錯別字，另一方面檢查是否存在語義表達等問題。
自己要對自己的成果負責。
5）可以讓同事幫忙檢查
有時很難發現自我產生的錯誤，因為會陷入慣性思維怪圈。因此找同事幫忙檢查也是不錯的方式。
而且相互幫助，去識別對方的錯誤，也能在很大程度上檢視自己，提升錯字意識。
以上這些方法都可以快速運用，幾乎“0門檻”，逐漸我們會提升錯別字的敏感程度，快速識別錯誤，并且能夠總結出一些“高頻錯字”。
多管齊下，立竿見影。
雖然經過幾百年的發展，文字表達從最初的文言文變成了白話文，但白話文也不代表等同于口語化。
我也見到過一些同行在吐槽文檔中為什么一定要用書面語，既費時又費力。而我個人認為原因在于這八個字：正式、規范、嚴肅、嚴謹。
其實如果是團隊內部的文檔，只要領導沒意見，你們愿意怎么搞就怎么搞。一旦涉及到對外輸出，邏輯嚴謹、表達清晰、結構明確的內容便是基礎。
在此我列舉幾個關鍵點，建議大家在寫文檔時盡量規避這些問題。
1）表達簡潔易懂
當然，可能有些文檔就是需要復雜嚴謹（比如專利申請文檔），讀起來非常拗口但確實挑不出邏輯漏洞。
不過我們大部分接觸的文檔，還是盡量簡單、易懂，從而讓讀者盡快理解你想表達的意思
比如：
2）避免歧義用詞
“一千個人心中有一千個哈姆雷特”，很多詞語都有多面性，當使用不恰當時，非常容易造成讀者的歧義。
所以我們在使用這些詞語時，要脫離自己的慣性思維，以用戶視角來審視這段話是否準確。
所以避免內容的“二義性”是內容規范中非常重要的一點。3）語義要直接，別讓對方反復理解
這里和表達簡潔易懂有幾分類似，但第一條更傾向于別說廢話，此條更傾向于業務邏輯盡量直接。
比如：
文件名一定不能隨便起，尤其是要發給客戶的文檔。最好能夠通過文件名能讓讀者明白此文檔的目的或核心內容。
而且文件名最好能夠和正文內的大標題保持一致，盡量在文件名中包含客戶的簡稱、版本號、或者修改日期，其中修改日期一般出現在后續版本修改之后再添加。
比如：
總之，不要忽略文檔名稱的重要性，如果起一個不專業的名字，可能對方都不會打開看就駁回了。
以上便是我對于“內容規范性”的總結，希望我們能給勤加練習，多多注意。
還有一些其他的注意事項，簡單整理供大家參考：
1、我們在寫文檔時，有些沒寫完的內容會習慣性標注出來，等到后續再完善，但此時的標注一定要很方便的讓你快速找到。比如采用特定的關鍵詞（todo、待完善），或者插入批注。
不要僅僅增加一個字體顏色或者背景色來標注。因為文檔如果很長、如果沒有逐行檢查，很有可能會遺漏。
2、文檔內容如果不是特別多，在多人協作時盡量使用【修訂模式】，避免協作過程中出現沖突或疏忽而產生內容問題。最終合并時再把修訂內容逐一核對，可以避免很多協同過程的麻煩。
當然，如果文檔較長，修訂模式會很卡，多人協作要么采用一些其他協同工具，要么做好分工，避免同一部分多人修改的情況。
3、較長的文檔，建議增加頁碼。
4、最好有“版本修訂記錄”，但不是必須。畢竟修改記錄后期維護起來非常繁瑣。如果文檔版本變動頻繁或者有追溯的必要性時，再增加修訂記錄也可以。
關于修訂記錄還需要注意一點：修訂的內容是否適合讓接收人看到？至于為什么，你可以細品一下，我就不多說了
5、從其他文檔復制進來的內容，一定要進行關鍵詞檢索。可以日常維護一個“關鍵詞詞庫”，包含其他客戶的名稱、其他產品的名稱、以及易錯的關鍵詞。待文檔完成后，進行全局檢索，大概率會有“驚喜”。
6、客戶給的模板，盡量不要在結構上大改。有些章節如果沒有內容，或者不知道怎么寫，可以標注“不適用”。但是如果你直接把章節刪掉，后續交付、審核時可能會被糾錯。當然，刪掉的前提也要和客戶溝通清楚。
以上，就是今天所有的分享，不知道你看完之后有沒有發現自己之前的小問題呢？
如果有，那就快去改吧。如果沒有，那么恭喜你，你的文檔能力已經超越了大多數產品同行，繼續加油吧。
“故不積跬步，無以至千里”，成長如此，文檔亦是如此。當我們把一個個小細節處理好之后，最終呈現的效果一定會不一樣。
我始終記得早些年因為文檔疏忽而踩過的坑、熬過的夜、被駁回的記錄，那一個個痛苦且煩悶的日子讓我逐漸意識到文檔的重要性。
我也記得身邊的幾位小伙伴在被我找出很多文檔基礎性問題時的無助與無奈。但好在，當我們真的開始注意這些問題時，一切都在向著更好的方向改變。
最后，正式、規范、嚴肅、嚴謹，不僅體現在文檔上，更應該體現在日常的工作中。
專欄作家
不想延期，公眾號：不想延期，人人都是產品經理專欄作家。半路轉行的B端泛金融產品，堅持“以實踐驗證理論，以輸出倒逼成長”的目標。點滴珍貴，重在積累
本文原創發布于人人都是產品經理，未經許可，禁止轉載。
題圖來自 Unsplash，基于CC0協議。
該文觀點僅代表作者本人，人人都是產品經理平臺僅提供信息存儲空間服務。