ijg jpeg 函數庫：代碼規則

ijg jpeg 函數庫：代碼規則 作者：未知

著作權 (c) 1991-1996, thomas g. lane. 本文是independent jpeg group軟體中的一部分。 針對於如何分發與使用，請參照隨本庫一起發放的readme 檔案。 由於很多程式員將會為完善代碼與bug修複中而共同努力，因此，統一編碼風格將是很重要的一件事。使用相似的編碼風格的目的不在於風格的細枝末節，而在統一的重要性。 一般，我們遵從推薦標準"recommended c style and coding standards"(c代碼標準和編碼風格推薦標準)的6.1版（cannon等人。由spencer, keppel和brader修訂）。該文檔可在ijg ftp目錄中找到(參見jpeg/doc/cstyle.ms.tbl.z，或者專為沒有nroff/tbl r的使用者提供的cstyle.txt.z)。 註解區塊應以下列方式布局： /* 　*　 block comments in this style. 　*/ 我們使用k&r風格來對語句進行縮排，例如， 　　　 if (test) < 　　　 　 then-part; 　　　 > else < 　　　 　 else-part; 　　　 > 每一級縮排使用兩個空格。（這種縮排習俗由gnu emacs或其他文字編輯器自動完成。） 多個單片語成的名稱應該以小寫加底線方式，例如，multi_word_name (不是multiwordname)。前置處理器符號和枚舉常量相似，但應使用大寫形式(multi_word_name)。在前15個字元之內，名稱應該保持唯一。（對一些老系統而言，全域變數名應在6位以內保持唯一。我們在不引起混亂的情況下，通過使用宏來代替較短的名稱的方法來解決這個問題。） 我們可在任何地方使用函數原形；我們依賴於自動代碼轉換來彌補缺少原型的c編譯器。轉換是通過簡單輕便的工具ansi2knr.c（蒙ghostscript的好意）來完成的。ansi2knr並不是很智能化，因此要求在函式宣告時要注意格式問題：函數名must begin in column 1。因此所有的函數都應該這樣寫： local(int *) function_name (int a, char *b) < 　　　 code... > 註：每個函數定義必須以global(type), local(type),或 methoddef(type)開頭。這些宏適當地擴充了"static type" 或僅僅是"type"。它們為函數的用法提供了一種可讀性較好的標識且可為特殊的需求備用。（例如，特殊的連結詞可被插入以便windows dlls使用。） ansi2knr不能轉換方法聲明（結構體的中的函式宣告）。我們用jmethod來解決，jmethod的定義如下： 　　　 #ifdef have_prototypes 　　　 #define jmethod(type,methodname,arglist)　 type (*methodname) arglist 　　　 #else 　　　 #define jmethod(type,methodname,arglist)　 type (*methodname) () 　　　 #endif 可被這樣使用： 　　　 struct function_pointers < 　　　 　 jmethod(void, init_entropy_encoder, (int somearg, jparms *jp)); 　　　 　 jmethod(void, term_entropy_encoder, (void)); 　　　 >; 註：應用圓括弧將參數列表括起來。 相似的解決方案用於提交和外部函式宣告（參見extern and jpp 宏）。 如果代碼將在非ansi編譯器上運行，我們將不能依賴於原型聲明將正確的類型填入真實的參數中。因此，無論何時，當實際的參數類型和聲明的不一致時，對真實的參數使用顯示的強制類型轉換（cast）。對隱式的"int"轉化要謹慎。 好像存在一些非ansi編譯器，其中的sizeof操作符被定義為返回一個int，然而size_t卻被定義為long。勿用置疑，這是傷腦筋的。我們使用 sizeof()宏來取代sizeof()，以便傳回值保證是size_t類型。 jpeg庫的目的是為了用在較大的程式中。此外，我們還想讓其更為靈活以便可以在並發的多種影像處理的應用中。下面的規則支援這些需求： 1.　　　 避免直接使用檔案i/o，"malloc"，錯誤報表輸出等；通過使用一般的函數來避開這些。 2.　減少全域變數汙染。無論何處，函數應儘可能聲明為static的。（註：我們基於方法的調用習慣有助於該問題的解決：在許多模組中，一般只有初始化函數是永遠需要被直接調用的，因此初始化函數需為外部可見的。）所有的全域函數名應以"jpeg_"開頭，並在need_short_external_names被設定的情況下，應該具有一個用宏來代替的簡簡短名稱（頭６個字元唯一）。 3.　不要使用全域變數；任何必須在另一個模組中使用的應該放在通用的資料結構中。 4. 除了唯讀常量表之外，不要使用靜態(static)變數。對某個模組私人的變數可以將其置於私人結構體當中(參見系統架構文檔，structure.doc)。 5. 對那些是庫的組成部分的源檔案名稱應該以‘j’為首字母；而非庫中組成部分的源檔案，例如，cjpeg.c和djpeg.c，就不需要以‘j’打頭了。保持檔案名稱為8字元（包括".c"或 ".h", 等）,以保證與ms-dos的相容。保持壓縮與解壓縮代碼放入分立的源檔案中---一些應用可能只需發它們中的一個。 註：這些規則（尤其是第四條）在使用cjpeg/djpeg，但並非jpeg庫中一部分的模組中並不是被篤信似地遵守。那些模組並不是真正地非要在其它模組中被使用。