This article is about the idea to adopt the concept of documentation comments like for Javadoc in CSS. It is a follower to my article in german: Adaption des Javadoc-Standards in CSS.

Javadoc is a writing convention of how to write comments into the sourcecode, please refer to the Wikipedia article if you need some of the basics. Since this is comming from the Programming and the OOP world in specific, all concepts related to programming do not match CSS. But since javadoc has a mature and widely accepted concept in structure and styling comments, even CSS can benefit from so called javadoc-styled comment-blocks (also named DocBlock) within it’s code.

This creates an intra-language / intra-code streamlined view on comments resulting in better readable and exchange-able files. Open Source Projects can benefit from these “coding-guidelines” because this helps a lot even in cases the guidelines are not the best ones. Additionally javadoc-styled comments are well readable and some projects might benefit from existing parsers from the programming world (javadoc; phpdocumentor etc.) even if this is not intended in the first place. Another Idea is to generate a better Readable “Documentation view” of your CSS files with crossreferences between sections and such.

Since it is clear that OOP related stuff from javadoc – and that is much – makes no sense to be used in a CSS-file (javadoc is used to automatically generate a API documentation where in a CSS file the commentblocks and tags are used for the documentation itself), the following general usage concept is proposed:

Comment-Types: File-, Section- and Hackcomment

Each CSS-File has a Filecomment-block on top which contains all major information about the file. After this first block zero or more Sections can be created by an according Sectioncomment-Block that is defined and named by an @section tag. This concept of structuring can already be found in many CSS files so this should reflect current practices very well.

One special thing for CSS are so called CSS-Hacks. You first write down the main CSS-Code and then it is extended with often only some but very special rules only to circumvent special display bugs in certain browsers. Wether you like it or not but it’s always good to mark these very special areas in your CSS document because these stylerules are important by the time of major changes or later problem solving. For these cases a so called Hackcomment-Block can be defined and named with an @hack tag. It comes with an @hackfor tag to write down for which useragent(s) and bug(s) the following style rules were written down.

“backward compability”

Some files within applications contain information within their CSS files that are used by the application itself. A Wordpress Theme for example contains metadata like the name of the theme and its author inside the CSS-file. Shure it would be nice if those themes would adopt a javadoc-styled-notation for these purposes as well (by parsing @author or introducing specific tags like @wp-theme-name or @wp-theme-uri) but an example implementation for javadoc-styled-comments in CSS should leave enough space for backward compability and common practices. That can be easily achieved by not forcing the first file-comment-block to be at the physical beginning of the file.

Javadoc Tags for CSS

This is an example set of Tagnames suggested for the usage of Javadoc-Styled-Comments in CSS. Feedback is greatly appreciated to make this list best fitting and a starting point for every CSS-Writer.

Der Beitrag wurde am Donnerstag, den 17. Mai 2007 um 09:14 Uhr veröffentlicht und wurde unter CSS, Home, Material abgelegt. Du kannst die Kommentare zu diesen Eintrag durch den RSS 2.0 Feed verfolgen. Du kannst einen Kommentar schreiben, oder einen Trackback auf deiner Seite einrichten.