CSSDOC是階層樣式表(Cascading Style Sheets,簡稱CSS)的一種寫作風格,可以幫助個人開發者與開發團隊改善CSS檔案的寫作/整理/管理等各方面的問題。CSSDOC使用知名的JavaDoc作法,以註解區塊(DocBlock)形式為原始碼寫作註解。它將CSS的格式、DocBlock註解以及註解使用的標籤(tag)整合在一起,為CSS檔案規範統一的寫作風格。
目前CSSDOC發展到2008年11月的第二次公開草案。CSSDOC的知名度不高,實際上這份草案也有很多未完成的部份。儘管如此,CSSDOC對於統一CSS的文件註解格式來說,已經是個可以參考的寫作指南。
就如CSSDOC所說,通常設計師撰寫CSS的風格並沒有統一,因此在交流CSS時會造成許多不方便。所以我想簡單地介紹一下CSSDOC的特色與用法,藉此也好好學習良好的CSS寫作風格。
使用CSSDOC的好處
儘管CSS寫作跟一般的物件導向式的程式語言不同,使用CSSDOC仍可以為程式設計師帶來幾個點好處:
統一寫作風格,促進程式交流
CSS設計師可以用CSSDOC來美化CSS檔案的版面,依此作為寫作風格的參考,以方便跟其他作者、作家、設計師、網頁開發者、創意指導等相關人員分享程式。
詳細註明相容性、錯誤修正與區隔設計
CSSDOC教導設計師跟軟體開發者如何在CSS的檔案中註明相容性、針對不同瀏覽器的錯誤修正與區隔設計的方法,讓開發與設計時可以更清楚地知道該段CSS語法的用意。
便於分析CSS檔案
撰寫的CSSDOC的CSS程式可以利用程式工具來剖析出額外的資料,就像JavaDoc可以產生標準格式的說明網頁一樣,目前也有利用Ruby實作的工具可以使用。
註解與文件區塊(DocBlock)介紹
CSSDOC採用類似JavaDoc的文件區塊(DocBlock)來撰寫CSS的文件,因此有必要先介紹一下文件區塊的樣貌。
/**
* Short Description
*
* Long Description
*
* @tag I am a tag named "tag"
* @other And I am a tag named "other"
*/
上面是一個文件區塊(DocBlock)的例子,撰寫CSSDOC的資訊都會在文件區塊當中。在這個例子中包含了短敘述(Short Description,通常是一行)跟長敘述(Long Description,實際上可能是好幾行的敘述),還有以「@」開頭的「@tag」跟「@other」標籤與後面接著的值,用來標示這個文件區塊的後設資料。
所謂的CSS註解,是以「/*」開頭、「*/」結尾,這之間的資料是給設計師閱讀、電腦會自動省略的區域。文件區塊則是以「/**」換行開頭(注意,多了一個*喔!)、最後一行以「*/」結尾的區塊。在閱讀時十分地顯眼。
有使用過JavaDoc、PHPDoc、JSDoc等各種註解的程式設計師,應該都很熟悉這種寫作風格。許多IDE也都支援文件區塊的寫法,你只要輸入「/**」開頭,按下Enter鍵之後,IDE就會自動幫你把後面的「 */」帶出來。
由於CSS並不是很正規的程式語言,所以它的文件區塊用法以及裡面的標籤與Java或PHP有些許不同。CSSDOC使用文件區塊將CSS檔案分成各個部分,也利用文件區塊來註明CSS特有的CSS修正與區隔設計用法。
CSS檔案的結構
在撰寫CSS的時候,一般我們會覺得CSS檔案結構很模糊。事實上我自己寫的時候,也常常隨處插入一個CSS語法,造成往後整理CSS時發生不少混亂的問題。
CSSDOC將CSS檔案區分成許多區塊來讓文件架構更為明確,如右圖所示。區塊分成兩種:檔案註解(File Comment)、區段註解(Section Comment),他們都是以文件區塊的方式撰寫而成。
檔案註解 (File Comment)
檔案註解位於檔案的開頭,一份CSS檔案只有一個檔案註解,目的是說明整份檔案的概要。
以下是檔案註解的範例:
/**
* Homepage Style
*
* Standard Layout (all parts) for Big Little Homepage
*
* This style has been designed by Mina Margin. It reflects
* the composition of colors through years
* customers project as well the boldness it implies.
*
* @project Big Little Homepage
* @version 0.2.8
* @package xhtml-css
* @author Mina Margin
* @copyright 2008 by the author
* @cssdoc version 1.0-pre
* @license GPL v3
*
* @colordef #fff; white
* @colordef #808080; standard grey
*/
除了短敘述(Homepage Style)與長敘述(Standard Layout……. it implies.)之外,還有包含數個標籤。各標籤的意義簡單介紹如下:
- @project:專案名稱
- @version:檔案版本
- @package:標示該檔案跟其他某些檔案一樣歸屬於某個包裹(package)中
- @author:作者
- @coptyright:版權聲明
- @cssdoc:標示使用的CSSDOC版本
- @license:標示此檔案的發行條款
- @colordef:指定顏色的色碼以及其名稱
區段註解 (Section Comment)
區段註解位於檔案之中,可以省略或是有多個區段註解,它用以說明一個區段的開始。區段註解會包含「@section」標籤,而區段底下還可以分出「子區段(subsection)」,使用「@subsection」標籤。範例如下:
/**
* Reset Section
*
* @section reset
*/
[...]
/**
* Reset Forms
* @subsection forms
*/
[...]
如果你需要使用CSS修正(CSS Fixes)或是針對不同瀏覽器製作的CSS區隔設計(CSS-HACKS),你也可以加入額外的區隔設計註解(Hack-Comment)。以下是一個區隔設計中CSS修正的範例與CSS語法,這是用來迴避IE5的顯示錯誤而撰寫的。
/**
* IE/Win Guillotine Bug
*
* @workaround
* @affected IE 5.x/Win, IE6
* @css-for IE 5.x/Win, IE6
* @valid yes
*/
* html body a,
* html body a:hover { background-color: transparent; }
這段區段註解包含了短敘述(IE/Win Guillotine Bug)以及數個標籤,說明如下:
- @workaround:標示這是一個解決程式錯誤的迴避方案(workaround),他並不能真正地解決程式的錯誤。
- @affected:標示錯誤修正(bugfix)或是替代方法(workarond)的目標瀏覽器
- @css-for:標示這段CSS語法是為了這些目標瀏覽器而撰寫的
- @valid:是否已經驗證了這段CSS語法
標籤 (tag)
標籤包含在文件區塊中,以「@」開頭呈現。文件區塊中標籤的用處是類似後設資料(Metadata),跟我們現今常見的社會性標籤是不同的意思。
從上面的例子中可以看到,標籤是以更有格式的形式說明特定的資訊。例如檔案註解裡面使用「@project Big Little Homepage」的標籤與標籤值,就能夠說明該檔案的專案名稱為「Big Little Homepage」。目前CSSDOC草案規範中標籤的值僅接受英數字與常見的標點符號,中文字似乎並沒有在規範內。
規定的格式不僅讓人便於閱讀,CSSDOC的分析器也能夠更準確地分析出各個註解的意義與關聯。在CSSDOC第一版草案中設計了32個推薦標籤,也有4個廢棄的標籤。我試著將他們分成六類:
- 檔案標註標籤:有些標籤是描述整個檔案的資訊,在其他文件工具也很常見,例如「@author」(作者)、「@copyright」(版權聲明);
- 區段標註標籤:有些是CSSDOC用來規範檔案架構的區段標籤,例如「@section」(區段名稱)、「@subsection」(子區段名稱);
- 參考資訊標籤:有些是註明參考資訊的標籤,例如「@see」(參見)、「@since」(參見版本);
- 檢測標籤:有些是標示檢測狀況的標籤,例如「@tested」(通過測試)、「@valid」(有效);
- 錯誤修正、迴避標籤:有些是CSS語法特有的相容性、錯誤修正、替代方案說明,例如「@bugfix」(錯誤修正)、「@css-for」(這段CSS語法是為了目標瀏覽器而寫);
- 其他標籤:有些是為了CSSDOC分析器而設計,例如「@cssdoc」(CSSDOC版本、分析器控制)。
熟知各個標籤的意義與用法是了解CSSDOC的必要功課,詳細的內容就請參考PDF中第三節的內文,或是我另一篇整理的CSSDOC標籤參考表。
結語
老師曾經說過一種句話,「要讓人家覺得你很專業,就要說這一行的行話」。如果要讓Java程式寫得看起來很專業,要學會使用JavaDoc;要讓PHP看起來很專業,要學會使用PHPDoc;那麼要讓CSS寫起來很專業,我想可以試著從CSSDOC開始。
編輯CSS的IDE編輯環境很多,但是支援CSSDOC的IDE卻不常見。我使用的Aptana Studio跟NetBeans都各自用各自的CSS註解,而不是使用常見的註解區塊。由於自己已經習慣了註解區塊與標籤的寫法,讓我在撰寫CSS時有也種不這樣做就渾身不對勁的感覺。至少沒有註解區塊的CSS,看起來就是一整個混亂且難以維護。所以我現在正學著使用CSSDOC來設計CSS檔案。
不過,CSS技術已經發展多年,但是CSSDOC的消息卻仍停留在2009年,至今也還沒有正式版本出來,前景真是令人堪憂啊。
(more...)
Comments