Compass Naming Conventions

[gmclelland]

Could you please let me know what the naming conventions are for
Compass?

I'm trying to put together the force-wrap mixin to contribute to
Compass, but I'm seeing different conventions in different places.

Examples:
compass/frameworks/compass/stylesheets/compass/typography/lists/ -
words are separated by hypens
compass/frameworks/compass/stylesheets/compass/typography/ - words are
separate by underscores
compass/test/fixtures/stylesheets/compass/sass - words are separate by
underscores
compass/doc-src/content/reference/compass/typography/lists - words are
separated by both underscores and hypens

If there isn't any convention, maybe we should start one going forward
to reduce confusion.

Just want make sure I do it right,
Glenn McLelland - gmclelland

[Chris Eppstein]

I would like to standardize on dashes. The imports should all already be dashes, unless I missed something when I deprecated things back at the start of v0.10. So I guess the confusion is around the documentation urls? I'm fine to rename them to match the import as long as we set up some redirects. I should probably check in the htaccess file...

chris

--
You received this message because you are subscribed to the Google Groups "Compass Development" group.
To post to this group, send email to compas...@googlegroups.com.
To unsubscribe from this group, send email to compass-devs...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/compass-devs?hl=en.

[gmclelland]

I didn't even think about the urls, that would definitely improve usability if all urls were consistent.

Side note:  It would also be cool, if you could easily access a mixin name by a predictable url like http://compass-style.org/mixin/box-shadow

Drupal does this with modules.  http://drupal.org/project/views

Makes it easy to configure bookmarks were you can just type "dp views" to lookup http://drupal.org/project/views

To be clear, I was confused by:

1. the mixin names, example nowrap, scaleZ, scale3d; should be no-wrap, scale-z and scale-3d  There seem to be quite a few that could be changed.
2. sass stylesheets file names, ex box_shadow.scss should be box-shadow.scss
3. file names for test fixtures, most fixtures filenames use underscores to separate spaces, should be hyphens for consistancy
4. haml documentation file names, example nowrap.haml should be no-wrap.haml; vertical_rhythm.haml should be vertical-rhythm.haml
   

What do you think?  That's a lot of changes, not sure how to handle backwards compatibility.

[Chris Eppstein]

On Mon, Mar 28, 2011 at 1:31 PM, gmclelland <glenn.m...@gmail.com> wrote:

I didn't even think about the urls, that would definitely improve usability if all urls were consistent.

Side note:  It would also be cool, if you could easily access a mixin name by a predictable url like http://compass-style.org/mixin/box-shadow

I guess we could generate a page per mixin, but I'm not sure it's entirely worth the effort. The search feature turns up mixins pretty well and there's these indices:

http://beta.compass-style.org/index/variables/

http://beta.compass-style.org/index/mixins/

http://beta.compass-style.org/index/functions/

 

Drupal does this with modules.  http://drupal.org/project/views

Makes it easy to configure bookmarks were you can just type "dp views" to lookup http://drupal.org/project/views

To be clear, I was confused by:

1. the mixin names, example nowrap, scaleZ, scale3d; should be no-wrap, scale-z and scale-3d  There seem to be quite a few that could be changed.

The inconsistencies in the scale mixins are actually inherited from the CSS3 spec. I prefer consistency with the CSS spec over internal consistency. For nowrap, I can see user's doing both, maybe we should have both forms. 

1. sass stylesheets file names, ex box_shadow.scss should be box-shadow.scss

Actually it's not. It's a dash: https://github.com/chriseppstein/compass/blob/master/frameworks/compass/stylesheets/compass/css3/_box-shadow.scss

 

1. file names for test fixtures, most fixtures filenames use underscores to separate spaces, should be hyphens for consistancy

test files are internal, I don't see a whole lot of value in renaming, but if you want to, I'll take the patch...

 

1. haml documentation file names, example nowrap.haml should be no-wrap.haml; vertical_rhythm.haml should be vertical-rhythm.haml
   

I do think it's nice if these match the imports. Like I said we just need to change the docs and then update the apache config to redirect old links. 

1. What do you think?  That's a lot of changes, not sure how to handle backwards compatibility.

We always deprecate before remove. so you have to keep the old names around, have them @warn the user and then call to the new name.

Crhis

[gmclelland]

I didn't even know about:

http://beta.compass-style.org/index/variables/

http://beta.compass-style.org/index/mixins/

http://beta.compass-style.org/index/functions/

Maybe you could place a link to these pages under "Reference" http://beta.compass-style.org/reference/compass/?  Unless I'm just missing something?

Yeah, mixins per page is probably overboard.  I just like doing http://www.chromeplugins.org/tips-tricks/custom-search-engines-in-google-chrome/ when possible.

Thanks for all you do,

-Glenn

[Chris Eppstein]

Those pages are linked from the search results page in the case where search doesn't turn up what you're looking for. I think that's a good place for them, tho I could be convinced otherwise -- brandon had a swath of changes he wanted to make...

Not sure if it's relevant, but I made a Google CSE for compass & sass a while ago:

http://www.google.com/cse/home?cx=010456759155788273473:zupmdc_kzci

[Alex Cabrera]

1. haml documentation file names, example nowrap.haml should be no-wrap.haml; vertical_rhythm.haml should be vertical-rhythm.haml

FWIW, I've adopted the following conventions in the sass directory of my Compass projects and think it's a generally nice way of organizing sass projects.

_foo-bar.sass

foo-bar/_mixins.sass

foo-bar/_config.sass

A few import conventions and you're set

_foo-bar.sass

------------------

@import "foo-bar/config"

@import "foo-bar/mixins"

_config.sass

----------------

$sane-default: value !default

_mixins.sass

----------------

@mixin super-shortcut($s: $sane-default)

     // Do something with $s

Dashed mixins work well because I prefer using underscores in my HTML class and id attributes (ie. <div id="page_header">) and it helps to visually differentiate between the element being defined and the mixins used to define it.

screen.sass

-----------------

@import "foo"

#page_header

    @include super-shortcut

You could then, of course, break screen up into it's own similar directory/import structure. It's great because you can I import as much or as little of your libraries as you want without having to worry about breaking stuff.

-

Alex Cabrera

Work: http://policus.com

Twitter: http://twitter.com/_alexcabrera

[Eric Meyer]

I like naming conventions where we can, but I think consistency with CSS should always remain the top consideration. And thus 'nowrap' also remains one word.