Skip to content

Better inline documentation #26

Open
martinklepsch opened this Issue Jan 30, 2010 · 17 comments

7 participants

@martinklepsch
Collaborator

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
tanila commented Jan 30, 2010

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

@stubbornella
Owner

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
Collaborator

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
Owner

@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
Collaborator

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
tanila commented Feb 24, 2010

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

concat files -> sprite file -> minify file

I prefer gnu make

@stubbornella
Owner

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
Collaborator

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
Collaborator

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
Collaborator

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
Owner

@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
SeanJA commented Feb 12, 2011

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)

@yodasw16 yodasw16 pushed a commit to yodasw16/oocss that referenced this issue May 21, 2011
@stubbornella issue #26: pop bug in IE6 dabb9e0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.