From 4262991eb9056e3c2ec05e7521b0e7a9f345bf04 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 11:21:48 +0100 Subject: [PATCH 01/36] file org draft notes --- _chapters/09-organisation.md | 42 ++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 _chapters/09-organisation.md diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md new file mode 100644 index 0000000..78b2357 --- /dev/null +++ b/_chapters/09-organisation.md @@ -0,0 +1,42 @@ +--- +layout: chapter +title: Organisation +section: Extras +permalink: /chapters/organisation/ +description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. +--- + +## Strategy 1 + + /basket + /templates + /whatever + /css + basket.css + +## Strategy 2 + + /path + /to + /css + /vendor + /yourApp + basket.css + +## Splitting out sections with a chunky comment + + /**************************************** + * Basket + ****************************************/ + + .basket { + /* etc */ + } + + .basket-title { + /* etc */ + } + +## 32 file limit + +Test IE9 \ No newline at end of file From c7735c6015e545304162ba4e101fefaf0253bccf Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 12:05:06 +0100 Subject: [PATCH 02/36] more notes --- _chapters/09-organisation.md | 38 ++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 78b2357..2b17cd3 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,7 +6,18 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -## Strategy 1 +*"Where do I find CSS?"* and *"Where do I put CSS?"* are questions we need to be able to answer if we are to write maintainable CSS. Shoving everything into one file isn't fun, but yet we can't just create a separate file per module as will be discussed in a sec. + +There are generally two ways in which we can organise these things. + +## Method 1: Put CSS in a CSS folder + + /css + /vendor + /yourApp + basket.css + +## Method 2: Put CSS within a module folder /basket /templates @@ -14,14 +25,21 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi /css basket.css -## Strategy 2 +Global stuff? Where to put global stuff when putting stuff in modules? + + /global + global.css - /path - /to - /css - /vendor - /yourApp - basket.css + /module1 + module1.css + module1.html + etc + +## 32 file limit + +Both organisation options suffer from the 32 file limit which occurs up until IE9, fixed in IE10. So if you have more than 32 modules which is pretty likely you're in trouble depending on your bundling approach. + +If you're using a preprocessor, you're probably fine, but then debugging is harder. ## Splitting out sections with a chunky comment @@ -36,7 +54,3 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi .basket-title { /* etc */ } - -## 32 file limit - -Test IE9 \ No newline at end of file From 95b50551007699f65e4a1ef047b2c569cdd2f674 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 12:21:30 +0100 Subject: [PATCH 03/36] More org notes --- _chapters/09-organisation.md | 40 ++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 2b17cd3..c091e97 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -41,6 +41,46 @@ Both organisation options suffer from the 32 file limit which occurs up until IE If you're using a preprocessor, you're probably fine, but then debugging is harder. +If you're not using a preprocessor, then you will likely need to think about what deserves it's own file and what needs to be grouped and how those things are grouped. + +For example, recently on a shop the following was used to organise: + + base.css + basket.css + brand.css + buttons.css + category.css + checkout.css + dashboard.css + department.css + editorial.css + forms.css + globalModules.css + header.css + homepage.css + productDetails.css + roadtTest.css + security.css + simpleBrand.css + staticPages.css + subCategory.css + +It's interesting because I don't think this is perfect or great but it's okay considering we decided not to use a preprocessor to make debugging and developing easier in some respects. + +But the thing is, buttons.css could have been shoved in global. Same goes for forms.css. + +Then you have header.css which is a global module but got so big that it warranted a file of it's own. + +And actually these are organised more by page, than module, because those modules are often only surfaced on a single page. + +All food for thought for deciding how to organise stuff. + +Also, bundling everything v.s. separate bundles per section or page. + +Could do account.css and shop.css etc. It's not perfect, but prefer easy debuggin and a pretty easy to navigate file system. + +Failing that, it's easy to search for a module in question as per the guidelines because the css will only reside in one place. So search to the rescue on that one. + ## Splitting out sections with a chunky comment /**************************************** From f04b157cbc739766d99fd2e703158fab0bc0af30 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 17:20:33 +0100 Subject: [PATCH 04/36] org --- _chapters/09-organisation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index c091e97..b706ec9 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,9 +6,9 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -*"Where do I find CSS?"* and *"Where do I put CSS?"* are questions we need to be able to answer if we are to write maintainable CSS. Shoving everything into one file isn't fun, but yet we can't just create a separate file per module as will be discussed in a sec. +Organising your CSS files is important. When you organise your CSS well, it makes finding CSS and adding new CSS much easier, improving general maintainability. -There are generally two ways in which we can organise these things. +There are generally two options when it comes to file organisation: ## Method 1: Put CSS in a CSS folder From 71ebda9fd4c6ff8079ba627c4606578a0635df80 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 19:31:30 +0100 Subject: [PATCH 05/36] file org --- _chapters/09-organisation.md | 56 +++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index b706ec9..7ed69c5 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,53 +6,75 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Organising your CSS files is important. When you organise your CSS well, it makes finding CSS and adding new CSS much easier, improving general maintainability. +Well-organised CSS files are an important aspect of MaintainableCSS. We want to make our CSS easy to find, update and add to over time as projects evolve and increase in size. -There are generally two options when it comes to file organisation: +There are generally two approaches when it comes to organising your CSS. Let's discuss each in turn. -## Method 1: Put CSS in a CSS folder +## 1. Put CSS in a CSS folder - /css +This approach places all CSS files in to a single folder as follows: + + /path/to/css /vendor /yourApp basket.css -## Method 2: Put CSS within a module folder +With this method, it's obvious where CSS lives. Often this folder might be copied elsewhere and prep'd for deploying to production. Having it all in one place simplifies this process. + +Whilst MaintainableCSS does a great job in making CSS modular, it is likely there will always be rules that are global, so having the easy decision to shove it all in one place leaves little room for error. + +This has been the approach that I have taken and been exposed to most often. + +## 2. Put CSS in a module folder + +This approach means that the CSS folder resides within the module it pertains to as follows: /basket + /controllers + BasketController.js /templates - /whatever + Basket.html /css basket.css + /header + ... -Global stuff? Where to put global stuff when putting stuff in modules? +This approach is great because it groups related functionality under a single module folder. Whether it's CSS, Javascript, HTML, Controllers, Views, Partials or whatever else, having it all grouped in one place improves portability, and often you're working on multiple bits relating to the same feature so this makes sense. + +This to me makes more sense than the first approach, and when I have used it, it works well. + +As with the first approach, there is always *some* global CSS to write, so this will have to reside somewhere that doesn't have a natural home like modules do. You end up needing a "GlobalStuff" folder anyway. /global global.css + etc.css + /header + ... + /basket + ... + +## The 32 CSS file limit problem + +Whatever approach you decide to take you may well need to be aware of the 32 CSS file limit problem. - /module1 - module1.css - module1.html - etc +In short, you can't include more than 31 CSS files in an HTML document in some browsers up to Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. -## 32 file limit +Meaning you can't create more than 31 files unless you jump through certain hoops to avoid this problem. For example, if you don't use a CSS preprocessor, then when you're in debug mode for local development, you're limited. -Both organisation options suffer from the 32 file limit which occurs up until IE9, fixed in IE10. So if you have more than 32 modules which is pretty likely you're in trouble depending on your bundling approach. +You could of course bundle these files into one, on save, but this can be problematic for development and debugging. -If you're using a preprocessor, you're probably fine, but then debugging is harder. +If you do use a CSS preprocessor, you're likely already doing this and won't experience this problem. If so, move along now. -If you're not using a preprocessor, then you will likely need to think about what deserves it's own file and what needs to be grouped and how those things are grouped. +If you want to debug the original CSS files, then you will have to get creative in using the 31 CSS files to their max. For example, recently on a shop the following was used to organise: base.css basket.css brand.css - buttons.css category.css checkout.css dashboard.css - department.css editorial.css forms.css globalModules.css From 0abb84fb164d71094745e957a082515181737926 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 13:31:17 +0100 Subject: [PATCH 06/36] File org edits --- _chapters/09-organisation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 7ed69c5..e847dc0 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,26 +6,26 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Well-organised CSS files are an important aspect of MaintainableCSS. We want to make our CSS easy to find, update and add to over time as projects evolve and increase in size. +Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS and knowing how to add to it, is important at all times, but moreso as a project evolves and gets bigger. -There are generally two approaches when it comes to organising your CSS. Let's discuss each in turn. +There are generally two approaches to consider. Let's discuss each in turn. -## 1. Put CSS in a CSS folder +## 1. The single CSS folder method -This approach places all CSS files in to a single folder as follows: +As per the name, all CSS resides in a single folder within your project. Something like this: /path/to/css /vendor /yourApp basket.css -With this method, it's obvious where CSS lives. Often this folder might be copied elsewhere and prep'd for deploying to production. Having it all in one place simplifies this process. +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). -Whilst MaintainableCSS does a great job in making CSS modular, it is likely there will always be rules that are global, so having the easy decision to shove it all in one place leaves little room for error. +This is the approach I have taken and been exposed to the most. -This has been the approach that I have taken and been exposed to most often. +It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. -## 2. Put CSS in a module folder +## 2. The CSS in a module folder method This approach means that the CSS folder resides within the module it pertains to as follows: From 7fa3267ad5fb15d4727c0ce8fd90c950311fb516 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 14:42:12 +0100 Subject: [PATCH 07/36] Organisation update --- _chapters/09-organisation.md | 93 ++++++++++-------------------------- 1 file changed, 26 insertions(+), 67 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index e847dc0..3d7719e 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -10,7 +10,7 @@ Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS There are generally two approaches to consider. Let's discuss each in turn. -## 1. The single CSS folder method +## 1. CSS in one folder As per the name, all CSS resides in a single folder within your project. Something like this: @@ -25,94 +25,53 @@ This is the approach I have taken and been exposed to the most. It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. -## 2. The CSS in a module folder method +## 2. CSS in separate folders -This approach means that the CSS folder resides within the module it pertains to as follows: +This option means that CSS resides within the module it pertains to: /basket /controllers - BasketController.js + ... /templates - Basket.html + ... + /partials + ... + /whatever + ... /css basket.css /header ... -This approach is great because it groups related functionality under a single module folder. Whether it's CSS, Javascript, HTML, Controllers, Views, Partials or whatever else, having it all grouped in one place improves portability, and often you're working on multiple bits relating to the same feature so this makes sense. +The nice thing with this is that all related functionality lives under a single folder relating to the module. -This to me makes more sense than the first approach, and when I have used it, it works well. +But what about global CSS? -As with the first approach, there is always *some* global CSS to write, so this will have to reside somewhere that doesn't have a natural home like modules do. You end up needing a "GlobalStuff" folder anyway. +You'll need a folder for global CSS (or global stuff in general) for rules applied globally. Something like: /global - global.css - etc.css - /header - ... + /css + resetPerhaps.css + global.css + etc.css /basket + ...as above... + /header ... ## The 32 CSS file limit problem -Whatever approach you decide to take you may well need to be aware of the 32 CSS file limit problem. - -In short, you can't include more than 31 CSS files in an HTML document in some browsers up to Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. - -Meaning you can't create more than 31 files unless you jump through certain hoops to avoid this problem. For example, if you don't use a CSS preprocessor, then when you're in debug mode for local development, you're limited. - -You could of course bundle these files into one, on save, but this can be problematic for development and debugging. - -If you do use a CSS preprocessor, you're likely already doing this and won't experience this problem. If so, move along now. - -If you want to debug the original CSS files, then you will have to get creative in using the 31 CSS files to their max. - -For example, recently on a shop the following was used to organise: - - base.css - basket.css - brand.css - category.css - checkout.css - dashboard.css - editorial.css - forms.css - globalModules.css - header.css - homepage.css - productDetails.css - roadtTest.css - security.css - simpleBrand.css - staticPages.css - subCategory.css - -It's interesting because I don't think this is perfect or great but it's okay considering we decided not to use a preprocessor to make debugging and developing easier in some respects. - -But the thing is, buttons.css could have been shoved in global. Same goes for forms.css. - -Then you have header.css which is a global module but got so big that it warranted a file of it's own. - -And actually these are organised more by page, than module, because those modules are often only surfaced on a single page. - -All food for thought for deciding how to organise stuff. - -Also, bundling everything v.s. separate bundles per section or page. +Whatever approach you decide to take you may need to be aware of the 31 CSS file limit. -Could do account.css and shop.css etc. It's not perfect, but prefer easy debuggin and a pretty easy to navigate file system. +In short, you can't include more than 31 CSS files in an HTML document in some browsers including Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. -Failing that, it's easy to search for a module in question as per the guidelines because the css will only reside in one place. So search to the rescue on that one. +If you have a compilation step for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem because all your files will be bundled up into one. -## Splitting out sections with a chunky comment +If you don't have a compilation step for local development—because debugging source files is easier this way—then like me, you may have to consider this 31 file limit. - /**************************************** - * Basket - ****************************************/ +Your options: - .basket { - /* etc */ - } +1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. +2. Make sure you don't go over 31 files. - .basket-title { - /* etc */ - } +If you choose the latter, then you can't really go down the modular route, as several different modules will need to reside in the same file, depending on the size of your website etc. \ No newline at end of file From cfe68f12f8d7f955703f0cd6483757644bb8c463 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 17:01:51 +0100 Subject: [PATCH 08/36] org --- _chapters/09-organisation.md | 68 ++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 3d7719e..4bf983f 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,7 +6,7 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS and knowing how to add to it, is important at all times, but moreso as a project evolves and gets bigger. +*Discoverability* is an important aspect of MaintainableCSS. The ease of tracking down CSS, as well as adding new CSS, becomes more and more important as a project grows in size. There are generally two approaches to consider. Let's discuss each in turn. @@ -15,61 +15,61 @@ There are generally two approaches to consider. Let's discuss each in turn. As per the name, all CSS resides in a single folder within your project. Something like this: /path/to/css - /vendor - /yourApp - basket.css + /vendor + /yourApp + resetPerhaps.css + global.css + basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style such as `body {}`, or if it's a module style such as `.basket {}`. -This is the approach I have taken and been exposed to the most. +CSS is often modified for deployment, and having all of it in one place simplifies this task. -It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. +This is the approach I have used the most, but it's not necessarily the best. ## 2. CSS in separate folders This option means that CSS resides within the module it pertains to: /basket - /controllers - ... - /templates - ... - /partials - ... - /whatever - ... - /css - basket.css + /controllers + ... + /templates + basket.html + emptyBasket.html + /partials + basketHeader.html + basketSummary.html + /whatever + ... + /css + basket.css /header - ... + ... -The nice thing with this is that all related functionality lives under a single folder relating to the module. +All related functionality lives under a single folder relating to the module. Lovely! -But what about global CSS? - -You'll need a folder for global CSS (or global stuff in general) for rules applied globally. Something like: +**But what about global CSS?** You'll need a folder for global CSS (or global stuff in general). Something like: /global - /css - resetPerhaps.css - global.css - etc.css + /css + resetPerhaps.css + global.css + etc.css /basket - ...as above... + ...as above... /header - ... + ... ## The 32 CSS file limit problem -Whatever approach you decide to take you may need to be aware of the 31 CSS file limit. - -In short, you can't include more than 31 CSS files in an HTML document in some browsers including Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. +Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -If you have a compilation step for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem because all your files will be bundled up into one. +In short, some browsers (such as IE9) will ignore all rules that are included in a 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. -If you don't have a compilation step for local development—because debugging source files is easier this way—then like me, you may have to consider this 31 file limit. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. -Your options: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: 1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. 2. Make sure you don't go over 31 files. From 09ba723690d236a66a3a9c51040157a2d8285e90 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 17:19:54 +0100 Subject: [PATCH 09/36] File org --- _chapters/09-organisation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 4bf983f..3834b55 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -71,7 +71,6 @@ If you **have a compilation step** for local development—as would be the c If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: -1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. -2. Make sure you don't go over 31 files. +The **first** option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. -If you choose the latter, then you can't really go down the modular route, as several different modules will need to reside in the same file, depending on the size of your website etc. \ No newline at end of file +The **second** option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route as your now limited to no more than 31 modules in an entire website. \ No newline at end of file From 33be042cb3bf16ad4b24fd038a8f36f6008177e4 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Thu, 9 Jun 2016 11:11:45 +0100 Subject: [PATCH 10/36] 31! --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 3834b55..8ffc515 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -61,7 +61,7 @@ All related functionality lives under a single folder relating to the module. Lo /header ... -## The 32 CSS file limit problem +## The 31 CSS file limit problem Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. From 997c137442014ce1ea62c99a9877c9b0744b1d60 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Thu, 9 Jun 2016 11:13:35 +0100 Subject: [PATCH 11/36] typo --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 8ffc515..6350467 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -65,7 +65,7 @@ All related functionality lives under a single folder relating to the module. Lo Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore all rules that are included in a 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +In short, some browsers (such as IE9) will ignore all rules that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. From 1ea39d0ac9dbdd2054866cb5eac6340b40d22829 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 10:15:30 +0100 Subject: [PATCH 12/36] More organisation rewriting and info --- _chapters/09-organisation.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 6350467..c36fa39 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,30 +6,32 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -*Discoverability* is an important aspect of MaintainableCSS. The ease of tracking down CSS, as well as adding new CSS, becomes more and more important as a project grows in size. +*Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. There are generally two approaches to consider. Let's discuss each in turn. ## 1. CSS in one folder -As per the name, all CSS resides in a single folder within your project. Something like this: +This approach places all CSS inside a single folder within your project. Something like this: /path/to/css /vendor + someLib.css + someOther3rdParty.css /yourApp resetPerhaps.css global.css basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style such as `body {}`, or if it's a module style such as `.basket {}`. +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style applied to the `body`, or if it's a module style applied to `.basket`. -CSS is often modified for deployment, and having all of it in one place simplifies this task. +This is useful for deployment purposes such as combining, minifying, compressing and revving because having all CSS in one place simplifies this task. This is the approach I have used the most, but it's not necessarily the best. ## 2. CSS in separate folders -This option means that CSS resides within the module it pertains to: +This approach places CSS within the module it pertains to: /basket /controllers @@ -49,7 +51,7 @@ This option means that CSS resides within the module it pertains to: All related functionality lives under a single folder relating to the module. Lovely! -**But what about global CSS?** You'll need a folder for global CSS (or global stuff in general). Something like: +**But what about global CSS?** You'll need a folder for global CSS (or perhaps global stuff in general). Something like: /global /css @@ -65,12 +67,14 @@ All related functionality lives under a single folder relating to the module. Lo Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore all rules that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +In short, some browsers (such as IE9) will ignore styles that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. -If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one during development. -If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to solve this problem. Your options are as follows: -The **first** option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. +The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. -The **second** option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route as your now limited to no more than 31 modules in an entire website. \ No newline at end of file +The *second* option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route, as you're now limited to no more than 31 modules in an entire website. + +When I have taken the second option, I have grouped modules by the pages or sections of a site that they relate to. For example, in a recent project I have had *checkoutHeader*, *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within a `checkout.css` file. \ No newline at end of file From c7acc453a2f04f226771486bd9b00013e6bcd4cc Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 10:16:47 +0100 Subject: [PATCH 13/36] Less fluff --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index c36fa39..03bf48a 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -8,7 +8,7 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi *Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. -There are generally two approaches to consider. Let's discuss each in turn. +There are two approaches to consider. Let's discuss each in turn. ## 1. CSS in one folder From e9a57105f3fec155b0ffab8a9b8d3dca65187d6d Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 19:53:30 +0100 Subject: [PATCH 14/36] New org chapter ready to go --- _chapters/09-organisation.md | 54 +++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 03bf48a..edd8f25 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -3,35 +3,35 @@ layout: chapter title: Organisation section: Extras permalink: /chapters/organisation/ -description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. +description: Learn how to organise your CSS files within your codebase. --- -*Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. +*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. There are two approaches to consider. Let's discuss each in turn. -## 1. CSS in one folder +## 1. CSS in a single folder -This approach places all CSS inside a single folder within your project. Something like this: +This approach places all CSS inside a single folder within your project: /path/to/css - /vendor - someLib.css - someOther3rdParty.css - /yourApp - resetPerhaps.css - global.css - basket.css + /vendor + someLib.css + someOther3rdParty.css + /yourApp + resetPerhaps.css + global.css + basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style applied to the `body`, or if it's a module style applied to `.basket`. +Third-party CSS files live under `/vendor` while the CSS you write should live under `yourApp` where you change the name of this to match the name of your project. -This is useful for deployment purposes such as combining, minifying, compressing and revving because having all CSS in one place simplifies this task. +This approach normally simplifies the deployment process because typically, the act of bundling, compressing and other such tasks, are applied to a single target directory. -This is the approach I have used the most, but it's not necessarily the best. +This is the approach I have used most often, but that does not mean it's necessarily the best approach. -## 2. CSS in separate folders +## 2. CSS in separate module folders -This approach places CSS within the module it pertains to: +This approach places module-specific CSS within module folder encapsulating all the related functionality under one roof: /basket /controllers @@ -42,16 +42,18 @@ This approach places CSS within the module it pertains to: /partials basketHeader.html basketSummary.html - /whatever + /js ... /css basket.css /header ... -All related functionality lives under a single folder relating to the module. Lovely! +If you, like me have used the first approach for a long time, this way of doing things can seem strange at first, but it's really nice to work with. -**But what about global CSS?** You'll need a folder for global CSS (or perhaps global stuff in general). Something like: +### But what about global CSS? + +You'll need a folder for global CSS or global stuff in general: /global /css @@ -65,16 +67,16 @@ All related functionality lives under a single folder relating to the module. Lo ## The 31 CSS file limit problem -Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. +Whatever approach you decide, make sure you're aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore styles that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +Some browsers, such as IE9, will ignore styles that are included in the 32nd file (or above). For production this is fine, because you should be bundling your CSS to reduce the amount HTTP requests, but for local development you normally want to work on the source files for easy debugging. -If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one during development. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry, because your files will be bundled up into one during development. -If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to solve this problem. Your options are as follows: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to address this. Your options are as follows: -The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. +The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers. -The *second* option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route, as you're now limited to no more than 31 modules in an entire website. +The *second* option would be to make sure you don't go over 31 files. Choosing this option probably means you can't take the second, modular approach (described above) because most websites will require more than 31 modules. -When I have taken the second option, I have grouped modules by the pages or sections of a site that they relate to. For example, in a recent project I have had *checkoutHeader*, *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within a `checkout.css` file. \ No newline at end of file +If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped `.deliveryAddress`, `.paymentDetails` and `.orderConfirmation` modules within a `checkout.css` file. \ No newline at end of file From c41c059210129246d6685c52a2b009ed7dca8587 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Tue, 14 Jun 2016 15:28:53 +0100 Subject: [PATCH 15/36] card description --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index edd8f25..4cdf1c7 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -3,7 +3,7 @@ layout: chapter title: Organisation section: Extras permalink: /chapters/organisation/ -description: Learn how to organise your CSS files within your codebase. +description: Learn how to organise your CSS files. --- *Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. From 7e8c2fbfb1570233cb8e8f42e5252adde6cdc5b7 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 20 Jun 2016 15:03:55 +0100 Subject: [PATCH 16/36] Move lines together --- _chapters/09-organisation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 4cdf1c7..58f2497 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,9 +6,7 @@ permalink: /chapters/organisation/ description: Learn how to organise your CSS files. --- -*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. - -There are two approaches to consider. Let's discuss each in turn. +*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. There are two approaches to consider. Let's discuss each in turn. ## 1. CSS in a single folder From 92efcec8ae6265ffc5400937d65e948459c10ac7 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 20 Jun 2016 18:12:04 +0100 Subject: [PATCH 17/36] tighten up copy --- _chapters/09-organisation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 58f2497..393a067 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -14,18 +14,18 @@ This approach places all CSS inside a single folder within your project: /path/to/css /vendor - someLib.css + some3rdParty.css someOther3rdParty.css /yourApp - resetPerhaps.css + some.css global.css basket.css -Third-party CSS files live under `/vendor` while the CSS you write should live under `yourApp` where you change the name of this to match the name of your project. +Third-party CSS files live under `/vendor` while the CSS you write should live under `/yourApp` where *yourApp* is the name of your project. This approach normally simplifies the deployment process because typically, the act of bundling, compressing and other such tasks, are applied to a single target directory. -This is the approach I have used most often, but that does not mean it's necessarily the best approach. +This is the approach I have used most often, but that does not mean it's necessarily the best. ## 2. CSS in separate module folders @@ -77,4 +77,4 @@ The *first* option would be to introduce a compilation step i.e. mimick what you The *second* option would be to make sure you don't go over 31 files. Choosing this option probably means you can't take the second, modular approach (described above) because most websites will require more than 31 modules. -If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped `.deliveryAddress`, `.paymentDetails` and `.orderConfirmation` modules within a `checkout.css` file. \ No newline at end of file +If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within the `checkout.css` file. \ No newline at end of file From f4581cf397d0ce5c8d96bb5f85ff7436703480cc Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 22 Jun 2016 11:39:12 +0100 Subject: [PATCH 18/36] Renamed files to be in right order --- _chapters/{09-organisation.md => 11-organisation.md} | 0 _chapters/{11-faqs.md => 12-faqs.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename _chapters/{09-organisation.md => 11-organisation.md} (100%) rename _chapters/{11-faqs.md => 12-faqs.md} (100%) diff --git a/_chapters/09-organisation.md b/_chapters/11-organisation.md similarity index 100% rename from _chapters/09-organisation.md rename to _chapters/11-organisation.md diff --git a/_chapters/11-faqs.md b/_chapters/12-faqs.md similarity index 100% rename from _chapters/11-faqs.md rename to _chapters/12-faqs.md From 90ad4a8ad14000fac9e805bc147c8a43a08905e5 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 11:21:48 +0100 Subject: [PATCH 19/36] file org draft notes --- _chapters/09-organisation.md | 42 ++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 _chapters/09-organisation.md diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md new file mode 100644 index 0000000..78b2357 --- /dev/null +++ b/_chapters/09-organisation.md @@ -0,0 +1,42 @@ +--- +layout: chapter +title: Organisation +section: Extras +permalink: /chapters/organisation/ +description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. +--- + +## Strategy 1 + + /basket + /templates + /whatever + /css + basket.css + +## Strategy 2 + + /path + /to + /css + /vendor + /yourApp + basket.css + +## Splitting out sections with a chunky comment + + /**************************************** + * Basket + ****************************************/ + + .basket { + /* etc */ + } + + .basket-title { + /* etc */ + } + +## 32 file limit + +Test IE9 \ No newline at end of file From 7188d074d87d27e6542475fceabb46bc8099a209 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 12:05:06 +0100 Subject: [PATCH 20/36] more notes --- _chapters/09-organisation.md | 38 ++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 78b2357..2b17cd3 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,7 +6,18 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -## Strategy 1 +*"Where do I find CSS?"* and *"Where do I put CSS?"* are questions we need to be able to answer if we are to write maintainable CSS. Shoving everything into one file isn't fun, but yet we can't just create a separate file per module as will be discussed in a sec. + +There are generally two ways in which we can organise these things. + +## Method 1: Put CSS in a CSS folder + + /css + /vendor + /yourApp + basket.css + +## Method 2: Put CSS within a module folder /basket /templates @@ -14,14 +25,21 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi /css basket.css -## Strategy 2 +Global stuff? Where to put global stuff when putting stuff in modules? + + /global + global.css - /path - /to - /css - /vendor - /yourApp - basket.css + /module1 + module1.css + module1.html + etc + +## 32 file limit + +Both organisation options suffer from the 32 file limit which occurs up until IE9, fixed in IE10. So if you have more than 32 modules which is pretty likely you're in trouble depending on your bundling approach. + +If you're using a preprocessor, you're probably fine, but then debugging is harder. ## Splitting out sections with a chunky comment @@ -36,7 +54,3 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi .basket-title { /* etc */ } - -## 32 file limit - -Test IE9 \ No newline at end of file From b3e2e4a5babcf86fdf1ee2724c65040c1fa09615 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 12:21:30 +0100 Subject: [PATCH 21/36] More org notes --- _chapters/09-organisation.md | 40 ++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 2b17cd3..c091e97 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -41,6 +41,46 @@ Both organisation options suffer from the 32 file limit which occurs up until IE If you're using a preprocessor, you're probably fine, but then debugging is harder. +If you're not using a preprocessor, then you will likely need to think about what deserves it's own file and what needs to be grouped and how those things are grouped. + +For example, recently on a shop the following was used to organise: + + base.css + basket.css + brand.css + buttons.css + category.css + checkout.css + dashboard.css + department.css + editorial.css + forms.css + globalModules.css + header.css + homepage.css + productDetails.css + roadtTest.css + security.css + simpleBrand.css + staticPages.css + subCategory.css + +It's interesting because I don't think this is perfect or great but it's okay considering we decided not to use a preprocessor to make debugging and developing easier in some respects. + +But the thing is, buttons.css could have been shoved in global. Same goes for forms.css. + +Then you have header.css which is a global module but got so big that it warranted a file of it's own. + +And actually these are organised more by page, than module, because those modules are often only surfaced on a single page. + +All food for thought for deciding how to organise stuff. + +Also, bundling everything v.s. separate bundles per section or page. + +Could do account.css and shop.css etc. It's not perfect, but prefer easy debuggin and a pretty easy to navigate file system. + +Failing that, it's easy to search for a module in question as per the guidelines because the css will only reside in one place. So search to the rescue on that one. + ## Splitting out sections with a chunky comment /**************************************** From 0e3b11999a821534f24f393f87d59d33c69cf7c7 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 17:20:33 +0100 Subject: [PATCH 22/36] org --- _chapters/09-organisation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index c091e97..b706ec9 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,9 +6,9 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -*"Where do I find CSS?"* and *"Where do I put CSS?"* are questions we need to be able to answer if we are to write maintainable CSS. Shoving everything into one file isn't fun, but yet we can't just create a separate file per module as will be discussed in a sec. +Organising your CSS files is important. When you organise your CSS well, it makes finding CSS and adding new CSS much easier, improving general maintainability. -There are generally two ways in which we can organise these things. +There are generally two options when it comes to file organisation: ## Method 1: Put CSS in a CSS folder From 9868fc483e7ebcded3fab798427ccbf9a189e98b Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 25 Apr 2016 19:31:30 +0100 Subject: [PATCH 23/36] file org --- _chapters/09-organisation.md | 56 +++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index b706ec9..7ed69c5 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,53 +6,75 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Organising your CSS files is important. When you organise your CSS well, it makes finding CSS and adding new CSS much easier, improving general maintainability. +Well-organised CSS files are an important aspect of MaintainableCSS. We want to make our CSS easy to find, update and add to over time as projects evolve and increase in size. -There are generally two options when it comes to file organisation: +There are generally two approaches when it comes to organising your CSS. Let's discuss each in turn. -## Method 1: Put CSS in a CSS folder +## 1. Put CSS in a CSS folder - /css +This approach places all CSS files in to a single folder as follows: + + /path/to/css /vendor /yourApp basket.css -## Method 2: Put CSS within a module folder +With this method, it's obvious where CSS lives. Often this folder might be copied elsewhere and prep'd for deploying to production. Having it all in one place simplifies this process. + +Whilst MaintainableCSS does a great job in making CSS modular, it is likely there will always be rules that are global, so having the easy decision to shove it all in one place leaves little room for error. + +This has been the approach that I have taken and been exposed to most often. + +## 2. Put CSS in a module folder + +This approach means that the CSS folder resides within the module it pertains to as follows: /basket + /controllers + BasketController.js /templates - /whatever + Basket.html /css basket.css + /header + ... -Global stuff? Where to put global stuff when putting stuff in modules? +This approach is great because it groups related functionality under a single module folder. Whether it's CSS, Javascript, HTML, Controllers, Views, Partials or whatever else, having it all grouped in one place improves portability, and often you're working on multiple bits relating to the same feature so this makes sense. + +This to me makes more sense than the first approach, and when I have used it, it works well. + +As with the first approach, there is always *some* global CSS to write, so this will have to reside somewhere that doesn't have a natural home like modules do. You end up needing a "GlobalStuff" folder anyway. /global global.css + etc.css + /header + ... + /basket + ... + +## The 32 CSS file limit problem + +Whatever approach you decide to take you may well need to be aware of the 32 CSS file limit problem. - /module1 - module1.css - module1.html - etc +In short, you can't include more than 31 CSS files in an HTML document in some browsers up to Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. -## 32 file limit +Meaning you can't create more than 31 files unless you jump through certain hoops to avoid this problem. For example, if you don't use a CSS preprocessor, then when you're in debug mode for local development, you're limited. -Both organisation options suffer from the 32 file limit which occurs up until IE9, fixed in IE10. So if you have more than 32 modules which is pretty likely you're in trouble depending on your bundling approach. +You could of course bundle these files into one, on save, but this can be problematic for development and debugging. -If you're using a preprocessor, you're probably fine, but then debugging is harder. +If you do use a CSS preprocessor, you're likely already doing this and won't experience this problem. If so, move along now. -If you're not using a preprocessor, then you will likely need to think about what deserves it's own file and what needs to be grouped and how those things are grouped. +If you want to debug the original CSS files, then you will have to get creative in using the 31 CSS files to their max. For example, recently on a shop the following was used to organise: base.css basket.css brand.css - buttons.css category.css checkout.css dashboard.css - department.css editorial.css forms.css globalModules.css From cad9bd943a1eb011a72f92c510c61178f6d7ae2c Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 13:31:17 +0100 Subject: [PATCH 24/36] File org edits --- _chapters/09-organisation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 7ed69c5..e847dc0 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,26 +6,26 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Well-organised CSS files are an important aspect of MaintainableCSS. We want to make our CSS easy to find, update and add to over time as projects evolve and increase in size. +Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS and knowing how to add to it, is important at all times, but moreso as a project evolves and gets bigger. -There are generally two approaches when it comes to organising your CSS. Let's discuss each in turn. +There are generally two approaches to consider. Let's discuss each in turn. -## 1. Put CSS in a CSS folder +## 1. The single CSS folder method -This approach places all CSS files in to a single folder as follows: +As per the name, all CSS resides in a single folder within your project. Something like this: /path/to/css /vendor /yourApp basket.css -With this method, it's obvious where CSS lives. Often this folder might be copied elsewhere and prep'd for deploying to production. Having it all in one place simplifies this process. +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). -Whilst MaintainableCSS does a great job in making CSS modular, it is likely there will always be rules that are global, so having the easy decision to shove it all in one place leaves little room for error. +This is the approach I have taken and been exposed to the most. -This has been the approach that I have taken and been exposed to most often. +It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. -## 2. Put CSS in a module folder +## 2. The CSS in a module folder method This approach means that the CSS folder resides within the module it pertains to as follows: From a1131f95b03471ff7b8164a5f13f5b3c06d993ee Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 14:42:12 +0100 Subject: [PATCH 25/36] Organisation update --- _chapters/09-organisation.md | 93 ++++++++++-------------------------- 1 file changed, 26 insertions(+), 67 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index e847dc0..3d7719e 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -10,7 +10,7 @@ Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS There are generally two approaches to consider. Let's discuss each in turn. -## 1. The single CSS folder method +## 1. CSS in one folder As per the name, all CSS resides in a single folder within your project. Something like this: @@ -25,94 +25,53 @@ This is the approach I have taken and been exposed to the most. It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. -## 2. The CSS in a module folder method +## 2. CSS in separate folders -This approach means that the CSS folder resides within the module it pertains to as follows: +This option means that CSS resides within the module it pertains to: /basket /controllers - BasketController.js + ... /templates - Basket.html + ... + /partials + ... + /whatever + ... /css basket.css /header ... -This approach is great because it groups related functionality under a single module folder. Whether it's CSS, Javascript, HTML, Controllers, Views, Partials or whatever else, having it all grouped in one place improves portability, and often you're working on multiple bits relating to the same feature so this makes sense. +The nice thing with this is that all related functionality lives under a single folder relating to the module. -This to me makes more sense than the first approach, and when I have used it, it works well. +But what about global CSS? -As with the first approach, there is always *some* global CSS to write, so this will have to reside somewhere that doesn't have a natural home like modules do. You end up needing a "GlobalStuff" folder anyway. +You'll need a folder for global CSS (or global stuff in general) for rules applied globally. Something like: /global - global.css - etc.css - /header - ... + /css + resetPerhaps.css + global.css + etc.css /basket + ...as above... + /header ... ## The 32 CSS file limit problem -Whatever approach you decide to take you may well need to be aware of the 32 CSS file limit problem. - -In short, you can't include more than 31 CSS files in an HTML document in some browsers up to Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. - -Meaning you can't create more than 31 files unless you jump through certain hoops to avoid this problem. For example, if you don't use a CSS preprocessor, then when you're in debug mode for local development, you're limited. - -You could of course bundle these files into one, on save, but this can be problematic for development and debugging. - -If you do use a CSS preprocessor, you're likely already doing this and won't experience this problem. If so, move along now. - -If you want to debug the original CSS files, then you will have to get creative in using the 31 CSS files to their max. - -For example, recently on a shop the following was used to organise: - - base.css - basket.css - brand.css - category.css - checkout.css - dashboard.css - editorial.css - forms.css - globalModules.css - header.css - homepage.css - productDetails.css - roadtTest.css - security.css - simpleBrand.css - staticPages.css - subCategory.css - -It's interesting because I don't think this is perfect or great but it's okay considering we decided not to use a preprocessor to make debugging and developing easier in some respects. - -But the thing is, buttons.css could have been shoved in global. Same goes for forms.css. - -Then you have header.css which is a global module but got so big that it warranted a file of it's own. - -And actually these are organised more by page, than module, because those modules are often only surfaced on a single page. - -All food for thought for deciding how to organise stuff. - -Also, bundling everything v.s. separate bundles per section or page. +Whatever approach you decide to take you may need to be aware of the 31 CSS file limit. -Could do account.css and shop.css etc. It's not perfect, but prefer easy debuggin and a pretty easy to navigate file system. +In short, you can't include more than 31 CSS files in an HTML document in some browsers including Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. -Failing that, it's easy to search for a module in question as per the guidelines because the css will only reside in one place. So search to the rescue on that one. +If you have a compilation step for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem because all your files will be bundled up into one. -## Splitting out sections with a chunky comment +If you don't have a compilation step for local development—because debugging source files is easier this way—then like me, you may have to consider this 31 file limit. - /**************************************** - * Basket - ****************************************/ +Your options: - .basket { - /* etc */ - } +1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. +2. Make sure you don't go over 31 files. - .basket-title { - /* etc */ - } +If you choose the latter, then you can't really go down the modular route, as several different modules will need to reside in the same file, depending on the size of your website etc. \ No newline at end of file From 4c82686fa01c4151f18a5d17053277c791ff61ec Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 17:01:51 +0100 Subject: [PATCH 26/36] org --- _chapters/09-organisation.md | 68 ++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 3d7719e..4bf983f 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,7 +6,7 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -Well-organised CSS files are an important aspect of MaintainableCSS. Finding CSS and knowing how to add to it, is important at all times, but moreso as a project evolves and gets bigger. +*Discoverability* is an important aspect of MaintainableCSS. The ease of tracking down CSS, as well as adding new CSS, becomes more and more important as a project grows in size. There are generally two approaches to consider. Let's discuss each in turn. @@ -15,61 +15,61 @@ There are generally two approaches to consider. Let's discuss each in turn. As per the name, all CSS resides in a single folder within your project. Something like this: /path/to/css - /vendor - /yourApp - basket.css + /vendor + /yourApp + resetPerhaps.css + global.css + basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style such as `body {}`, or if it's a module style such as `.basket {}`. -This is the approach I have taken and been exposed to the most. +CSS is often modified for deployment, and having all of it in one place simplifies this task. -It's obvious where CSS lives whether it is a global rule such as `body {}` or if it's a module such as `.basket {}`. Additionally, these assets are often modified for deployment, and having them all in one place simplifies this task. +This is the approach I have used the most, but it's not necessarily the best. ## 2. CSS in separate folders This option means that CSS resides within the module it pertains to: /basket - /controllers - ... - /templates - ... - /partials - ... - /whatever - ... - /css - basket.css + /controllers + ... + /templates + basket.html + emptyBasket.html + /partials + basketHeader.html + basketSummary.html + /whatever + ... + /css + basket.css /header - ... + ... -The nice thing with this is that all related functionality lives under a single folder relating to the module. +All related functionality lives under a single folder relating to the module. Lovely! -But what about global CSS? - -You'll need a folder for global CSS (or global stuff in general) for rules applied globally. Something like: +**But what about global CSS?** You'll need a folder for global CSS (or global stuff in general). Something like: /global - /css - resetPerhaps.css - global.css - etc.css + /css + resetPerhaps.css + global.css + etc.css /basket - ...as above... + ...as above... /header - ... + ... ## The 32 CSS file limit problem -Whatever approach you decide to take you may need to be aware of the 31 CSS file limit. - -In short, you can't include more than 31 CSS files in an HTML document in some browsers including Internet Explorer 9. What happens is any CSS that resides in an additional file will be ignored. +Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -If you have a compilation step for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem because all your files will be bundled up into one. +In short, some browsers (such as IE9) will ignore all rules that are included in a 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. -If you don't have a compilation step for local development—because debugging source files is easier this way—then like me, you may have to consider this 31 file limit. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. -Your options: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: 1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. 2. Make sure you don't go over 31 files. From f605574492902a2d3ef320e2cfd47802bd2632fa Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 8 Jun 2016 17:19:54 +0100 Subject: [PATCH 27/36] File org --- _chapters/09-organisation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 4bf983f..3834b55 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -71,7 +71,6 @@ If you **have a compilation step** for local development—as would be the c If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: -1. Introduce a compilation step i.e. mimick what you're doing for production so that you can test in offending browsers such as IE9 when necessary. -2. Make sure you don't go over 31 files. +The **first** option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. -If you choose the latter, then you can't really go down the modular route, as several different modules will need to reside in the same file, depending on the size of your website etc. \ No newline at end of file +The **second** option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route as your now limited to no more than 31 modules in an entire website. \ No newline at end of file From a1cf218550aa27e259c18de9cef0a77ff06c0c0a Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Thu, 9 Jun 2016 11:11:45 +0100 Subject: [PATCH 28/36] 31! --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 3834b55..8ffc515 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -61,7 +61,7 @@ All related functionality lives under a single folder relating to the module. Lo /header ... -## The 32 CSS file limit problem +## The 31 CSS file limit problem Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. From a94d344861ca037f081abba1a90a9b8fc4e79725 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Thu, 9 Jun 2016 11:13:35 +0100 Subject: [PATCH 29/36] typo --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 8ffc515..6350467 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -65,7 +65,7 @@ All related functionality lives under a single folder relating to the module. Lo Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore all rules that are included in a 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +In short, some browsers (such as IE9) will ignore all rules that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. From 7068c7739d1ab40abe4c63c441d6baac5b7f055d Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 10:15:30 +0100 Subject: [PATCH 30/36] More organisation rewriting and info --- _chapters/09-organisation.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 6350467..c36fa39 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,30 +6,32 @@ permalink: /chapters/organisation/ description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. --- -*Discoverability* is an important aspect of MaintainableCSS. The ease of tracking down CSS, as well as adding new CSS, becomes more and more important as a project grows in size. +*Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. There are generally two approaches to consider. Let's discuss each in turn. ## 1. CSS in one folder -As per the name, all CSS resides in a single folder within your project. Something like this: +This approach places all CSS inside a single folder within your project. Something like this: /path/to/css /vendor + someLib.css + someOther3rdParty.css /yourApp resetPerhaps.css global.css basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style such as `body {}`, or if it's a module style such as `.basket {}`. +If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style applied to the `body`, or if it's a module style applied to `.basket`. -CSS is often modified for deployment, and having all of it in one place simplifies this task. +This is useful for deployment purposes such as combining, minifying, compressing and revving because having all CSS in one place simplifies this task. This is the approach I have used the most, but it's not necessarily the best. ## 2. CSS in separate folders -This option means that CSS resides within the module it pertains to: +This approach places CSS within the module it pertains to: /basket /controllers @@ -49,7 +51,7 @@ This option means that CSS resides within the module it pertains to: All related functionality lives under a single folder relating to the module. Lovely! -**But what about global CSS?** You'll need a folder for global CSS (or global stuff in general). Something like: +**But what about global CSS?** You'll need a folder for global CSS (or perhaps global stuff in general). Something like: /global /css @@ -65,12 +67,14 @@ All related functionality lives under a single folder relating to the module. Lo Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore all rules that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +In short, some browsers (such as IE9) will ignore styles that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. -If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one during development. -If you **don't have a compilation** step for local development—because debugging source files is easier this way—then like me, you may have to solve this problem. Your options are as follows: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to solve this problem. Your options are as follows: -The **first** option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. +The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. -The **second** option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route as your now limited to no more than 31 modules in an entire website. \ No newline at end of file +The *second* option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route, as you're now limited to no more than 31 modules in an entire website. + +When I have taken the second option, I have grouped modules by the pages or sections of a site that they relate to. For example, in a recent project I have had *checkoutHeader*, *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within a `checkout.css` file. \ No newline at end of file From 74429b6b947fe90d996ef62ed4467e297676f3c4 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 10:16:47 +0100 Subject: [PATCH 31/36] Less fluff --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index c36fa39..03bf48a 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -8,7 +8,7 @@ description: Learn how MaintainableCSS suggests to organise your CSS files withi *Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. -There are generally two approaches to consider. Let's discuss each in turn. +There are two approaches to consider. Let's discuss each in turn. ## 1. CSS in one folder From 81d0f92e4de7ba39f5114ec1ba332bb9d1208940 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 13 Jun 2016 19:53:30 +0100 Subject: [PATCH 32/36] New org chapter ready to go --- _chapters/09-organisation.md | 54 +++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 03bf48a..edd8f25 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -3,35 +3,35 @@ layout: chapter title: Organisation section: Extras permalink: /chapters/organisation/ -description: Learn how MaintainableCSS suggests to organise your CSS files within your codebase. +description: Learn how to organise your CSS files within your codebase. --- -*Discoverability* is an important part of writing maintainable CSS. And, the ease of tracking down CSS, becomes more and more important as a project grows in size. +*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. There are two approaches to consider. Let's discuss each in turn. -## 1. CSS in one folder +## 1. CSS in a single folder -This approach places all CSS inside a single folder within your project. Something like this: +This approach places all CSS inside a single folder within your project: /path/to/css - /vendor - someLib.css - someOther3rdParty.css - /yourApp - resetPerhaps.css - global.css - basket.css + /vendor + someLib.css + someOther3rdParty.css + /yourApp + resetPerhaps.css + global.css + basket.css -If you're using any third party CSS files, they should live in `/vendor`. Everything else should live in `/yourApp` (change the name to match your project). All CSS lives under this one folder whether it's a global style applied to the `body`, or if it's a module style applied to `.basket`. +Third-party CSS files live under `/vendor` while the CSS you write should live under `yourApp` where you change the name of this to match the name of your project. -This is useful for deployment purposes such as combining, minifying, compressing and revving because having all CSS in one place simplifies this task. +This approach normally simplifies the deployment process because typically, the act of bundling, compressing and other such tasks, are applied to a single target directory. -This is the approach I have used the most, but it's not necessarily the best. +This is the approach I have used most often, but that does not mean it's necessarily the best approach. -## 2. CSS in separate folders +## 2. CSS in separate module folders -This approach places CSS within the module it pertains to: +This approach places module-specific CSS within module folder encapsulating all the related functionality under one roof: /basket /controllers @@ -42,16 +42,18 @@ This approach places CSS within the module it pertains to: /partials basketHeader.html basketSummary.html - /whatever + /js ... /css basket.css /header ... -All related functionality lives under a single folder relating to the module. Lovely! +If you, like me have used the first approach for a long time, this way of doing things can seem strange at first, but it's really nice to work with. -**But what about global CSS?** You'll need a folder for global CSS (or perhaps global stuff in general). Something like: +### But what about global CSS? + +You'll need a folder for global CSS or global stuff in general: /global /css @@ -65,16 +67,16 @@ All related functionality lives under a single folder relating to the module. Lo ## The 31 CSS file limit problem -Whatever approach you decide to take you may need to be aware of the 31 CSS file limit problem. +Whatever approach you decide, make sure you're aware of the 31 CSS file limit problem. -In short, some browsers (such as IE9) will ignore styles that are included in the 32nd file or above. For production this is fine, because you should be bundling and compressing your CSS for performance etc. +Some browsers, such as IE9, will ignore styles that are included in the 32nd file (or above). For production this is fine, because you should be bundling your CSS to reduce the amount HTTP requests, but for local development you normally want to work on the source files for easy debugging. -If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry about this problem, because all your files will be bundled up into one during development. +If you **have a compilation step** for local development—as would be the case if you're using a CSS preprocessor—you don't need to worry, because your files will be bundled up into one during development. -If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to solve this problem. Your options are as follows: +If you **don't have a compilation** step for local development—because debugging source files is easier this way—then you may have to address this. Your options are as follows: -The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers such as IE9. +The *first* option would be to introduce a compilation step i.e. mimick what you're doing for production, so you can—where necessary—debug in offending browsers. -The *second* option would be to make sure you don't go over 31 files. Choosing this option will likely mean you can't go down the modular route, as you're now limited to no more than 31 modules in an entire website. +The *second* option would be to make sure you don't go over 31 files. Choosing this option probably means you can't take the second, modular approach (described above) because most websites will require more than 31 modules. -When I have taken the second option, I have grouped modules by the pages or sections of a site that they relate to. For example, in a recent project I have had *checkoutHeader*, *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within a `checkout.css` file. \ No newline at end of file +If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped `.deliveryAddress`, `.paymentDetails` and `.orderConfirmation` modules within a `checkout.css` file. \ No newline at end of file From 915aeeeded37f36aa8e649f9c7eba3ff5ad1121f Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Tue, 14 Jun 2016 15:28:53 +0100 Subject: [PATCH 33/36] card description --- _chapters/09-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index edd8f25..4cdf1c7 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -3,7 +3,7 @@ layout: chapter title: Organisation section: Extras permalink: /chapters/organisation/ -description: Learn how to organise your CSS files within your codebase. +description: Learn how to organise your CSS files. --- *Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. From 7963590f44f322b4986e15bf08a9bc7469ce8a76 Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 20 Jun 2016 15:03:55 +0100 Subject: [PATCH 34/36] Move lines together --- _chapters/09-organisation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 4cdf1c7..58f2497 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -6,9 +6,7 @@ permalink: /chapters/organisation/ description: Learn how to organise your CSS files. --- -*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. - -There are two approaches to consider. Let's discuss each in turn. +*Discoverability* is an important part of writing maintainable stylesheets and this becomes more important as a project grows in size over time. There are two approaches to consider. Let's discuss each in turn. ## 1. CSS in a single folder From 558ceca073221971f749946e55d38d248ad8507c Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Mon, 20 Jun 2016 18:12:04 +0100 Subject: [PATCH 35/36] tighten up copy --- _chapters/09-organisation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_chapters/09-organisation.md b/_chapters/09-organisation.md index 58f2497..393a067 100644 --- a/_chapters/09-organisation.md +++ b/_chapters/09-organisation.md @@ -14,18 +14,18 @@ This approach places all CSS inside a single folder within your project: /path/to/css /vendor - someLib.css + some3rdParty.css someOther3rdParty.css /yourApp - resetPerhaps.css + some.css global.css basket.css -Third-party CSS files live under `/vendor` while the CSS you write should live under `yourApp` where you change the name of this to match the name of your project. +Third-party CSS files live under `/vendor` while the CSS you write should live under `/yourApp` where *yourApp* is the name of your project. This approach normally simplifies the deployment process because typically, the act of bundling, compressing and other such tasks, are applied to a single target directory. -This is the approach I have used most often, but that does not mean it's necessarily the best approach. +This is the approach I have used most often, but that does not mean it's necessarily the best. ## 2. CSS in separate module folders @@ -77,4 +77,4 @@ The *first* option would be to introduce a compilation step i.e. mimick what you The *second* option would be to make sure you don't go over 31 files. Choosing this option probably means you can't take the second, modular approach (described above) because most websites will require more than 31 modules. -If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped `.deliveryAddress`, `.paymentDetails` and `.orderConfirmation` modules within a `checkout.css` file. \ No newline at end of file +If you decide to limit the amount of CSS files you will need to work out how best to group modules into a single CSS folder. As an example, I recently grouped *deliveryAddress*, *paymentDetails* and *orderConfirmation* modules within the `checkout.css` file. \ No newline at end of file From 99415da38d4a49b663ca5b52c9b9a95cc57403af Mon Sep 17 00:00:00 2001 From: Adam Silver Date: Wed, 22 Jun 2016 11:39:12 +0100 Subject: [PATCH 36/36] Renamed files to be in right order --- _chapters/{09-organisation.md => 11-organisation.md} | 0 _chapters/{11-faqs.md => 12-faqs.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename _chapters/{09-organisation.md => 11-organisation.md} (100%) rename _chapters/{11-faqs.md => 12-faqs.md} (100%) diff --git a/_chapters/09-organisation.md b/_chapters/11-organisation.md similarity index 100% rename from _chapters/09-organisation.md rename to _chapters/11-organisation.md diff --git a/_chapters/11-faqs.md b/_chapters/12-faqs.md similarity index 100% rename from _chapters/11-faqs.md rename to _chapters/12-faqs.md