
18F: CSS coding style guide - molecule
https://18f.gsa.gov/2016/01/11/introducing-the-css-coding-style-guide/
======
YngwieMalware
This is a pretty good style guide and has a lot of habits I've been practicing
for many years now (even pre-sass/less).

Slightly off topic, I'm slightly bothered by the amount of trash talk CSS
receives since it's pretty much the best language we've ever had to define
interface styles, and it's only getting better. Maybe some of the rules about
behavior are arguable, but by and large I've never met a design I couldn't get
to work with some well-defined CSS.

And if you can't read nested CSS I can't imagine how you'd feel in the face of
some heavy XML.

~~~
Pxtl
I often think the existence of CSS can be seen as the strongest criticism of
XML: when designing a language to store styling attributes for HTML, they used
their own heirarchical format instead of another SGML-derivative.

~~~
felixgallo
I think you overestimate the amount of considered, thoughtful reflection that
went into creating HTML, CSS and JavaScript.

~~~
YngwieMalware
And yet they have become useful far beyond their original intended design.

~~~
felixgallo
No. They have prevented aeons of progress. They are an unmitigated computing
tire fire that future generations are going to curse us for.

~~~
olavk
Yeah, if just full-screen Java Applets had prevailed instead of web pages we
would be much better off! Seriously, the html/css/js stack has its share of
haphazard design, but it has shown to be much more robust and adaptable than
any of the proposed "better-designed" alternatives.

~~~
YngwieMalware
Yeah I do wish I could see a bunch of unstyled, barely functional UX
"designed" by engineers who have no understanding of interfaces or design.

------
liquidise
Nested selectors are some of the least maintainable language features i have
ever worked with. Once the number of embedded classes, or layers of embedding
gets too big, the entire file descends to a bad place.

Here is a real world example of what i am talking about, from a code base i
currently work with, and don't dare touch:
[http://i.imgur.com/fMlvoRS.png](http://i.imgur.com/fMlvoRS.png)

The idea of maintaining legacy sass with heavy embedding in years to come
makes me shudder.

~~~
pcurve
That is pretty bad. Sadly I've seen much worse.

Most sites don't need variables and nestings of CSS.

I would rather see duplicate class names like this in CSS.

.wrapper1 .header {}

.wrapper1 .header h2 {}

.wrapper1 .body {}

.wrapper1 .body .article {}

.wrapper1 .body .article .blurb {}

.wrapper1 .body .article .quote {}

.wrapper1 .footer {}

Repetition doesn't bother me. In fact, it is surprisingly helpful.

~~~
stdbrouw
So you'd also prefer

    
    
      if wrapper and header:
        ...
      if wrapper and body:
        ...
    

to

    
    
      if wrapper:
        if header:
          ...
        if body:
          ...
    

when coding?

~~~
id

      Two If statements, no nesting
    
      vs.
    
      Three If statements, 1 level deep nesting
    

To me, the first option is clearly simpler and more readable. Then again,
looking at the second option I notice immediately that I can dismiss it if
wrapper happens to be false. But it really depends on what the other code
lines contain.

~~~
obelisk_
I have never really considered repeating conditions instead of nesting. I
might try doing so next time since I'm generally not happy with the depth of
nesting I sometimes land myself in.

The problem I foresee with repeat conditions is that during a change, I might
forget to update one or more of the repeat conditions.

Also, I wonder, do gcc and/or clang recognize repeat conditions and produce
the equivalent of what nested statements would?

~~~
johnmaguire2013
Python taught me some good practices in regards to this. Python's
"enforcement" (or rather, strong PEP-8 suggestions) of 80 characters per line
teaches you to come up with a lot of ways to avoid nesting.

The most useful one, and the one that drives me crazy when I see it, is when
people write code like this:

    
    
        if something:
          value = do something
        else:
          value = do something else
    
        return value
    

These days I write code like this:

    
    
        if something:
          return do something
    
        return do something else
    

In the simple example, it's not a big deal. But once you have 30 lines of code
in between each statement (and nested if statements), it gets trickier to
maintain every possible code path in your head.

This isn't the same as "show all conditions at once" \-- instead it's "ignore
the conditions that have already been satisfied."

Seeing that we already returned out in condition #1 lets me focus more on
condition #2.

~~~
thaumasiotes
> Python's "enforcement" (or rather, strong PEP-8 suggestions) of 80
> characters per line teaches you to come up with a lot of ways to avoid
> nesting.

> The most useful one, and the one that drives me crazy when I see it, is when
> people write code like this:

But... your example doesn't show any ways to avoid nesting. There's just as
much nesting after as before.

Your change makes the code less tall, which is a problem I've had with Python,
but it has nothing to do with nesting at all.

I'm actually fond of a third approach:

    
    
        if something:
            return do something
        else:
            return do something else
    

I like the ocaml-style philosophy that it's an error if your condition check
isn't capable of handling all possible conditions.

~~~
johnmaguire2013
I figured readers could fill in the relevant blanks. Updated example:

    
    
        if something:
          value = do something
        else:
          if something_else:
            value = do something else
          else:
            value = do a third thing
    

As I said in my initial post, "it helps once you have nested ifs, and multiple
lines of code." Here's the change:

    
    
        if something:
          return do something
    
        if something_else:
          return do something else
    
        return do a third thing
    

Again, what I'm stressing here is that if you already have your result, you
can return, and it makes the code easier to follow than adding a superfluous
"else:" statement.

------
kevan
I believe the linter is the important part here. I've come to the conclusion
that style guides are only useful if they come with a linter that fails
builds. It's way too easy to put code into a repo that works but doesn't live
up to the style guide and once code hits trunk it's a lot harder to rework it.

~~~
matt_wulfeck
I'll go you one further and say it shouldn't only be optionally enforced, it
should just happen. The less I have to think about style the more I can focus
on design.

In the future every new language should come with a "go fmt" equivalent.

~~~
kevan
Auto-formatting is great, but it can't handle everything. For example, our
ESLint config prevents modification of function params[1]. I don't think a
tool could automatically reformat this into compliance without changing the
behavior of the code, a human needs to look at the failure and change it.

[1][http://eslint.org/docs/rules/no-param-
reassign.html](http://eslint.org/docs/rules/no-param-reassign.html)

~~~
matt_wulfeck
That's a ultimately a "problem" with the initial language design. If you
design it with the intention of using auto formatters you won't run into these
issues.

I originally didn't like braces in go, but then I realized there's just enough
in there to make auto-formatting easy.

~~~
50CNT
I think language design may be too strong a term for a lot of web technology.
That's where you want to be using a linter and/or validator though.

------
avitzurel
I choose to see the positive here.

Yes, you can criticize the nested classes and inconsistencies of brace
placement. (And you should).

But I love seeing things coming out of 18F. I think this sort of open gov
computing projects are blessed.

Even if you're not 100% open source but your development is "in the open",
that's a huge step towards a better service to citizens.

------
kevinwuhoo
Somewhat related, I've been pleasantly surprised by the number of design
manuals that US and other government agencies are releasing. Some notable
favorites are:

* CIO: [https://playbook.cio.gov/designstandards/](https://playbook.cio.gov/designstandards/)

* CFPB: [https://cfpb.github.io/design-manual/](https://cfpb.github.io/design-manual/)

* GOV.UK: [http://govuk-elements.herokuapp.com/](http://govuk-elements.herokuapp.com/)

Hope to see more open gov open source projects in the future.

------
matthewlein
Their modified BEM choice is surprising. I think BEM works best when the
dividers have meaning. In their examples its impossible to know what is a
modifier vs an...element? I don't get it from the examples.

    
    
      .accordion
      .accordion-item
      .accordion-item-selected
    
      .nav_bar
      .nav_bar-link
      .nav_bar-link-clicked
    

Though its the most ugly, I'm a fan of the original B__E--M

~~~
Nadya
_> Though its the most ugly, I'm a fan of the original B__E--M_

I feel this is something people need to learn to look past - because I agree
_entirely_. It looks terrible. Absolutely terrible. Names get long (but yay
for autocompleters!) - but everything is readable. CSS shouldn't be aesthetic.
It should be legible. Maintaining something you can't read is hell - every
programmer knows this.

I also make use of prefixes to namespace. Which makes my classes even longer.
[0]

But there is absolutely _no_ question what my code is doing when I read the
HTML. I know exactly where changes need to be made. My coworkers are familiar
enough with my style that _they_ know what code is safe to change and what
code will have side effects. They're slowly adopting the style - although it's
almost a 180 from the old style of "be as specific as possible so you don't
accidentally break something someone else had worked on 8 months ago".
(#NotEvenKidding .our .selectors .are > .like .this)

[0] [http://csswizardry.com/2015/03/more-transparent-ui-code-
with...](http://csswizardry.com/2015/03/more-transparent-ui-code-with-
namespaces/)

------
cjhveal
Is it just me, or does the screenshot from the blog post show code with
inconsistent open-brace placement near the td selector? I quickly looked at
the format section but but didn't see that style anywhere.

~~~
andrefrancisco
Yup. Good eye. We've updated the post with a new image.

*I'm an 18F employee.

------
reader_1000
It is interesting to see that they recommend againts using Bootstrap:

    
    
      18F specifically does not recommend using Bootstrap for production work because of one, 
      the difficulty in adapting its opinionated styles to bespoke design work and two, 
      its CSS style places semantic layout instructions directly in HTML classes.
    

[https://pages.18f.gov/frontend/css-coding-
styleguide/framewo...](https://pages.18f.gov/frontend/css-coding-
styleguide/frameworks/)

~~~
Finnucane
I agree with them. I work in an academic setting where accessibility is
important, and Bootstrap makes a hash of semantics, which is bad for assisted
reading systems that need it for navigation.

~~~
reader_1000
Accessibility is important for us too. What do you use if you don't mind
sharing? There is a accessibility plugin for bootstrap from Paypal [1]. Have
you ever tried it? Thanks.

[1] [https://github.com/paypal/bootstrap-accessibility-
plugin](https://github.com/paypal/bootstrap-accessibility-plugin)

------
matthewmacleod
This is only somewhat related, but I find it really interesting that the vast
majority of outfits using Sass opt for the SCSS syntax rather than the native
one.

Personally I always opt for the latter, since I find it heavily reduces the
amount of syntactic noise, which is a personal bugbear of mine. is the main
reason for using SCSS the familiarity, or the fact it's a strict superset of
CSS, or just that people generally dislike whitespace sensitivity? I can see
the benefits, but it would be interesting to know if there's another angle I
haven't considered.

~~~
jakobloekke
Probably, the main reason is that it's a superset of CSS. The
learning/migration path is extremely low.

------
epimetheus
I was curious what their standards for indents were:

"Use soft-tabs with a two space indent."[0]

Ugh, I work in Gov (DOD) and we recently switched to two spaces (I'm a
Java/PhP dev and have always used 4 spaces) and was hoping to use this to
support a switch back, guess that's a no go...

[0] - [https://pages.18f.gov/frontend/css-coding-
styleguide/format/](https://pages.18f.gov/frontend/css-coding-
styleguide/format/)

~~~
wavefunction
I prefer tabs for indentation because then the developer can set their IDE to
two space or four space or 8 space or whatever, the tab functions as an
abstract unit easily convertible to "one level of indentation."

~~~
epimetheus
Truth be told, I had switched to tabs (4 space tabs), mostly because my JS
linter complained about spaces and I didn't have very strong feelings about it
(in hindsight, it's probably a simple config setting).

------
deadowl
I never really thought to do anything like .classname.classname

~~~
jordanlev
Yeah that's pretty clever (I hasn't thought of it before either). Reminds me
of another hack/trick I saw recently, where you just put :root in front of a
selector to bump up its specificity.

------
cheriot
Yes, I read 18F, but where are you from?

------
AlexB138
Not related to this directly, but Jez Humble just joined 18F, which I found
surprising, but great.

------
binthere
More like SCSS coding style guide.

~~~
hardwaresofton
SCSS/SASS/LESS are _NOT_ CSS, I wish people would stop treating them as the
same.

 __* Caution, rant below __*

I also get really annoyed when people introduce SCSS/SASS/LESS in introductory
texts. Confuse a beginner right out of the gate with these template languages
that were made to work around CSS, which works perfectly fine, but is just
slightly inconvenient because it doesn't offer near-programming-language
levels of sugar/complexity.

/rant

------
marklawrutgers
Is it okay to minify .css files for production or does it not really matter
that much?

~~~
SquareWheel
It's usually recommended. Source maps help you still find right line numbers
and test changes, while minification+concatenation lets you write CSS across
many files without worrying about HTTP requests.

Do note this practice may be discouraged as HTTP2 gains wider adoption.

~~~
tomschlick
> Do note this practice may be discouraged as HTTP2 gains wider adoption.

Concatenation yes, minifying is always a good thing though.

~~~
ZeroGravitas
Concatenation still helps under HTTP2 due to better compression (more similar
stuff in one file), but the individual files can't be cached/evicted/updated
individually, you can't just load the bits you need for the current page, and
you can't prioritise certain parts to load first.

What the new standard approach will be I'm not sure.

~~~
SquareWheel
I'm guessing caching would be prioritized over the improved compression rates,
except in very specific circumstances. Though we'll also see improvements
there as brotli starts to replace gzip and deflate.

------
xufi
Interesting. THis should be helpful as I delve more into this area

------
brianzelip
Surprised to see (sass) selector nesting.

------
billburcham
I am intrigued by 18F itself (the organization). Employees are on the "GS"
scale (GS-14 thru GS-16). From the "Joining 18F" site's "Government pay grades
explained" [https://pages.18f.gov/joining-18f/pay-
grades/](https://pages.18f.gov/joining-18f/pay-grades/)

"… you cannot work at 18F on your position description for more than four
years … We believe that in this industry most people aren't going to stick
around for four years and beyond. They will join 18F, do their years of
service in the federal government, and then return to the private (or public)
sector. Due to the high-pressure nature of our work, it makes sense that
people will move on after a couple of years. That helps 18F stay fresh and
strong."

What the frack?!? Isn't the whole point of working for the Federal Government
to have a job for life? 18F is actually worse than (non-startup) private
sector jobs in that your contract says you cannot stay in the job longer than
2 (or 4) years. Fascinating.

~~~
dragonwriter
> What the frack?!? Isn't the whole point of working for the Federal
> Government to have a job for life?

No, though certainly the opportunity for a long-career with a stable employer
is part of the attraction for some people of some federal positions.

OTOH, even term-limited positions like those at 18F don't really conflict with
this, they just mean you need to find a _different_ federal position before
the term ends, leveraging your 18F experience.

> 18F is actually worse than (non-startup) private sector jobs in that your
> contract says you cannot stay in the job longer than 2 (or 4) years.

Limited-term-contract, non-startup, private sector jobs where you need to line
up a new gig before the contract expires to keep working are not exactly
uncommon, so I'm not sure how you characterize 18F as worse than non-startup
private sector jobs based on a feature it shares with many non-startup,
private sector jobs.

~~~
billburcham
> I'm not sure how you characterize 18F as worse than non-startup private
> sector jobs

Just seems like there is a mismatch between 18F's (high) cool factor and the
compensation structure. These pay rates do not strike me as "contracting" or
"consulting" rates. They strike me as more in line with "full time employee"
pay rates at ordinary private-sector (non-startup) companies. But the job term
is capped like a contract job. I don't see the financial upside to match their
statement that [https://pages.18f.gov/joining-18f/pay-
grades/](https://pages.18f.gov/joining-18f/pay-grades/):

"Due to the high-pressure nature of our work, it makes sense that people will
move on after a couple of years."

Sounds all startupy without the startup upside.

~~~
wslack
> But the job term is capped like a contract job.

I work at 18F, but am speaking for myself here. Pay rates and length of
service are both tied to existing rules for federal employment. The advantage
of being part of the government (and thereby following these rules) is in the
possible impact of our work, like working with the FEC to build a new website
with intermediate releases: [https://beta.fec.gov/](https://beta.fec.gov/)

