Better inline documentation

[martinklepsch]

Hey, when i look at mod.css i think there is room for improvement concerning documentation.

With cssdoc (look into the pdfs at the bottom of the page) we could use docblocks like:
/*
* This is the standard module
*
* @valid yes
* @tested no
* @package module
* @version 1.4 * and a lot more
/

The docTags mentioned above are especially useful when used in plugins also it would make understanding for newbies a lot easier.

What do you think?
I think it would be a great addition and easy to implement since the codebase isnt that huge at the moment.

Martin

[tanila]

I think this is a goo idea. Especially documenting the css-hacks etc to make it clear why things are done this way.

[stubbornella]

I like the idea of using better comments, we need an easy way to build compressed versions of the files (maybe tools from Yahoo! or Google?). Unfortunately, lots of people will use the files directly however we provide them. We'll need to compress, remove comments, maybe even combine them.

[martinklepsch]

It's a learning process. People should understand why it's better to use minified copies than the original code (Also it should be explained in the docs).
An idea i had some time is to have one master file that @imports all needed stylesheets but this is another discussion. I'll create a ticket about this soon.

[stubbornella]

@imports aren't great for performance because there are still lots of http requests. Ideally a site should only have one css file in production. (The only exception is the very most complicated websites)

[martinklepsch]

Hehe. I knew that some people will get this wrong. :)
My plan was not to use this master file in production. My plan was to use a master file for development for easy integration of oocss files. Doing so you dont need to mess in your . I dont see a reason to not do it the way i suggested.

Before deployment the @imports in this file should be replaced by the content of these files. Then minifying etc. pp.

[tanila]

as the yahoo-people reccomended: allways use a build tool :)

concat files -> sprite file -> minify file

I prefer gnu make

[stubbornella]

I have an idea, what if we do a build step in the project. Like YUI we can have a dev version and a minified version. That will allow more flexibility in comments, etc. Then, each time we have a new version, we auto-run the build tool to create the minified version. Would that work?

[martinklepsch]

Yep, thats actually the best way i think.

I think creating a branch 'minified' where the compressed files live would work well.

This way we dont need to mess with the directory structure and can switch even on production environments quickly between minified and regular.

That allows easier debugging & performance if needed.

I dont know how to do it technically but that probably isn't a big deal. (pre commit hooks or so)

[martinklepsch]

I just noticed that this wouldnt solve the whole problem since there would be many different files, which would result in many requests. Any ideas how to improve that?

[eric-brechemier]

My two cents: use Natural Docs [1] for the documentation and Combiner [2] to combine CSS files before minification. I am using these tools as part of a build process based on Apache Ant, for Javascript files, and they should work equally well with CSS files.

[1] Natural Docs http://www.naturaldocs.org/

[2] Introducing Combiner, a JavaScript/CSS concatenation tool, by Nicholas Zakas http://www.nczonline.net/blog/2009/09/22/introducing-combiner-a-javascriptcss-concatenation-tool/

[eric-brechemier]

Follow-up: using Natural Docs to generate HTML documentation for CSS requires some extra configuration.

You need to declare the language and associate it with CSS extension. This is done by inserting the following lines in the file Language.txt of Natural Docs Config folder:

Language: CSS

  Extension: css
  Block Comment: /* */

[phpwalter]

I would like to voice my view that development code should be readable and formatted.

Production code should be minified, etc, but that should be "up to the reader", as they say. And yes, many will just use these files as they are, but that is a lesson they need to learn.

When I have spent a bit of time this afternoon re-formatting the new code I pulled down today, just so I could read and understand it. This completely screws me when I try to merge any future changes. I can't merge. I have to toss what I have and re-format again.

My 2 cents: let those who wish to use the "full text" use them, please don't streamline this code for them. I think streamlining makes it harder for those of us trying to learn the code.

Thanks

[martinklepsch]

I think Natural Docs would be a bad choice since it's mainly built to document functions etc. – Things you don't really have in CSS.

What I found recently is Docco. The link explains it probably better than I would.

[eric-brechemier]

@mklappstuhl, despite having recommended Natural Docs, which seemed a good choice at the time based on its language-neutral stance, I have to admit after 8+ more months of use on both JavaScript and CSS inline documentation that the tool is not ideal. There are actually deeply rooted assumptions about programming languages, like expecting that functions will be documented with comments before each function, that have to be turned around. Also, the keywords provided by default are not ideal for CSS: it is awkward to document CSS rules as "classes" when they target elements or pseudo-elements.

On the other hand, I have a hard time reading the side by side documentation generated by Docco. Literate programming should not prevent you from putting comments within the code. Also, literate programming tools a la Knuth should allow to order the comments independently from the code order.

Edit (December 28, 2010): it is actually possible to define new keywords or alter the behavior of keywords in Natural Docs. Reference: http://www.naturaldocs.org/customizingtopics.html

[stubbornella]

@phpwalter - everyone has a different idea about the right way to format code. I format it the way I like to read it, which is one line per selector. There are editors (css edit, i think?) that will let you view it however you want and save it in a way that matches our style.

[gmclelland]

Why not just use SASS? Comments can be written in the .scss file and can optionally be removed when the css is compiled. Also, using .sass or .scss a file, one can choose to use the preshipped compiled version of OOCSS or create their own custom compiled version. This would allow for one line selector and properties. See http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#output_style for more info.

[SeanJA]

There are also online css re-formatters, I have one on my site:

http://seanja.com/tools/csstidy/

(Set the compression to low/normal to reformat the css for readability if you don't like the inline formatting)