9 ms·
A small guide for naming stuff in front-end code
- toastal 5y ago> Functions that do things (don’t have a return) These aren’t functions; these are effects.
- marcusbuffett 5y agoIn math and Haskell, sure, but this is wrong, not just pedantic. They are functions. The language docs call them functions. The keyword to create them is “function”.
- isleyaardvark 5y agoFor js and qa needs I’d recommend custom html data attributes instead of using classes (data-js=, data-qa=). It’s a much clearer separation of concerns.
- paceaux 5y agoI've tried that approach in the past. The reason I didn't promote it in the guide is because data attributes, in my experience, were more verbose than what we needed. They were useful in cases where we needed to pass in additional information (e.g. data-qa="onClick"). But what we found was - whether class or attribute, it was the same dependency on markup - selecting with [data-qa] was the same specificity as .qa - selecting with [data-qa] was just a little more verbose than the teams liked But, this isn't me arguing against data attributes. I'm just stating that my experience went in the direction where we didn't see any huge benefit. They're guidelines so, by all means, take what works, throw away the rest. This was a small guideline about how to name stuff, not build entire apps. So if that's the thing that doesn't work for your workstream, my feelings aren't hurt. Thanks for reading it, though, and sharing your thoughts.
- isleyaardvark 5y agoI tend to do it that way because I tend to use Atomic css, and that has enough classnames already.
- kenjackz 5y agoIt is easier to put and name the functionalities in a same category
- SavantIdiot 5y agoPackagers solve the caching issue. Despite their complexity and annoyances, it's hard to go back now.
- reidjs 5y agoPeople still think about naming their CSS classes? I thought we were all on Vue or Styled Components in React and tailwind?
- runarberg 5y agoYou still have to name some classes even if you use component scoped styles, however it is usually pretty straight forward. I quite often just name my classes something like: link, action, title, label, etc. Also when I’m writing forms, I usually name every field e.g. email-field so and then assign them in the grid using the class name: .email-field { grid-area: email }
- reidjs 5y agoI was being a bit facetious, I meant you don’t have to put much thought because when they’re scoped or in modules you can just name them the way you’re naming them. Complex CSS naming rules (like BEM style) seem dated to me.
- AltruisticGapHN 5y agoThis is actually super bad practice. I really dislike scoped css. When I see devs using scoped css the class names always end up like `.box` or `.name`. Having to think about classnames and writing Sass makes me much more aware of the structure of the components I'm styling. Also scoped CSS kinda makes you skip the steps of thinking about your component in the bigger picture of your site, since you don't care about having meaningful and unique classnames, then you're much less inclined to think about good guidelines like OP's conventions. What does it matter? Since we can just put a `.box` in the scoped <style> and call it a day. Frankly I think only JS oriented devs like scoped CSS and frontend who love html/css and the challenges of architecturing good CSS don't egt any benefit out of styled components (since you're using atomic css like Tailwind and/or BEM-style which always "scopes" classnames with the component name. In general any solid guidelines makes CSS instantly 10x better and that's all most projects needs, and it's often what most projects lack. SuitCSS works great with Vue in my experience, and can even be linted with postcss-bem-linter : https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md https://github.com/suitcss/suit/blob/master/doc/naming-conve...
- not2b 5y agoMostly good but I hate getProperty names. If a method returns the temperature call it temperature() not getTemperature(). If the private data member has to have a different name, _temperature or some similar convention will do.
- unholiness 5y agoIn JS (and in any expression-inside-html front end framework) this leads to the hugely common bug if (this.finished) { ... or <div v-if="showMainContent>... With your convention, these could easily be functions, but they are never evaluated without parens. Nor is any error thrown. Instead, the fact that the function exists is truthy and you get the true case always. In our teams's js code we even include "get" for "is" properties (getIsEnabled() rather than isEnabled()) so that it's perfectly obvious if you're ever using a function without calling it.
- ravenstine 5y agoExcept it's also likely, perhaps more so, that `this.finished` is `undefined`, which results in fundamentally the same problem but in the opposite direction of truthiness. In which case I still see it as just a personal preference. The prefix of "is" becomes reassurance that something is intended to have a boolean value, which may be more important. Of course it goes without saying that both of these things are (usually) addressed by a system like Typescript.
- emptysea 5y agoTypeScript will produce an error when using a function inside and if stmt without calling it: function f() {} if (f) {} produces: This condition will always return true since this function is always defined. Did you mean to call it instead?(2774) https://www.typescriptlang.org/play?#code/GYVwdgxgLglg9mABMAFASkQbwL4CgbCIrAY5A https://www.typescriptlang.org/play?#code/GYVwdgxgLglg9mABMA...
- not2b 5y agoIt seems that a linter tool would catch this even if TypeScript isn't used. In any case even if "get" is used, a coder might accidentally write if (getBooleanProperty) { ... } omitting the parens.
- stickfigure 5y agoI have one frontend naming habit that might be worth sharing. The root element of my react components always have a className that matches the component name exactly (ie capitalized). All other classNames are uncapitalized. Makes navigation pretty easy in browser dev tools.
- jamespetercook 5y agoThe BEM naming convention for css works matches this concept quite well
- marcusbuffett 5y agoGreat tip, will be stealing this.
- paceaux 5y agoI'm the original author. Somewhere else on my blog is an article about using BEM with content management systems (which is my area of specialization). I basically endorsed your exact practice, but with __content models__. The idea being that a content model could have multiple presentations (views), but still relies on a single core .... data model. So the Block is that data model and the modifier is the view. So your practice is 100% what I would endorse. This is a sample of the CSS guidelines I'd produce for my teams where you'll see that I explain it a bit more: https://gist.github.com/paceaux/f31e278613ab29b74a412a7eb5046422#bem https://gist.github.com/paceaux/f31e278613ab29b74a412a7eb504...
- onion2k 5y agoThe component heirarchy tool in React Devtools (https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en https://chrome.google.com/webstore/detail/react-developer-to...) lets you select something in the page and then click a button to go to it's component definition in the code (if your sourcemaps are working properly). It's the angled brackets in the right hand side panel - https://imgur.com/a/ufCPsMo https://imgur.com/a/ufCPsMo It's very useful.
- stickfigure 5y ago
- graup 5y agoThe general ideas are fine, but the examples are pretty outdated. For modern SPA, CSS naming has become largely obsolete. A lot of the JS code shows the principles it is supposed to well but sadly includes other cruft. Here's a guide I would recommend instead: https://github.com/labs42io/clean-code-typescript https://github.com/labs42io/clean-code-typescript
- froddd 5y agoThere is a huge amount of content besides SPAs on the internet. May this continue.
- motoxpro 5y agoNo opinion about the SPA thing but that guide is awesome. Thank you
- paceaux 5y agoI'm the original author All of the examples are within the last 2 years. My area of specialization is enterprise content management; I build the CMS AND the front-end for very large companies that use decoupled CMSs and web sites. And very often, the web app is a typical server-side .net app where a front-end team has written static HTML and handed it off to back-end developers to be sliced into views. So all of this stuff kinda comes from over a decade of doing THAT; it's fair to say that maybe this doesn't all apply if you're an app dev. But even when I DO build SPAs (like I am for one client), I still use CSS in traditional stylesheets as much as possible because any inline styling that doesn't invoke the CSSOM directly like it should seems like a massive waste of DOM resources ... and also I feel like I lose out on reusability that way. That "clean code for typescript" is really good. I may drop a link to it in mine. I wasn't trying to be exhaustive. I was just trying to set a good baseline for where to go ;)
- joppy 5y agoGreat post! Your code example for isHot() seems round the wrong way; also doing something like “return temperature > 100” is probably more idiomatic than using if/else just to return true/false.
- mrblampo 5y agoInteresting but a bit short on reasons. For example, why is it important for class names used by JS to find elements have a special prefix?
- undreren 5y agoI would guess that it is a convention used to highlight a code dependency. “If you remove or rename this class, the code will break.”
- PostThisTooFast 5y ago
- paceaux 5y agoThat's a really valid criticism. I'll update it. Thanks!
- dvh 5y agoI love when I return to some project after few years, realize I need some new feature, write the function name only to find out that the exactly the same function already exists and does what I want. When I choose the same name after so long it means there is some serious consistency in my naming conventions. Feels good.
- twic 5y agoSometimes i write a little function, think "hmm, i remember i did something like this before", do a search, and find a function with the same name, and exactly the same implementation. That is always really pleasing!
- seanwilson 5y ago> If you’re the first person on the project, use camelCase; it’s easier to select camelCased text in an IDE than it is hyphenated text Doesn't this go against the conventions of the most popular CSS libraries that your code will likely be used with? It's a pain and ugly that JavaScript and CSS don't use the same conventions though. The IDE select issue is probably fixable e.g. https://stackoverflow.com/questions/45590695/visual-studio-select-word-with-hyphen https://stackoverflow.com/questions/45590695/visual-studio-s...
- stickfigure 5y agoAnother advantage of camelCase is that classNames (https://github.com/JedWatson/classnames https://github.com/JedWatson/classnames) works without quoting: // you have a variable isFoo <SomeComponent className={classNames({isFoo})} /> is a lot better than: // you have a variable isFoo <SomeComponent className={classNames({'is-foo': isFoo})} /> (also, I personally shorten `classNames` to `cn` because it's so universally useful)
- seanwilson 5y agoYep, it would be nice if HTML/XML/CSS/Javascript/YAML/JSON/SQL identifiers were all standardised as it's not uncommon to see all of them in the same project.
- paceaux 5y agoSo, worth explaining (as I've told other folks here), my experience is in enterprise content management, usually building good ol' fashioned websites that are running on .net and getting content from a CMS. For the entirety of my career, I never ONCE worked with a CSS library. Every single one of my clients (who were on the Fortune 500 list, usually) had too unique of a design and too many different types of pages for us to bring in an external CSS library. So, for that reason, when I wrote these guidelines internally some years ago, we weren't concerned in the least with what CSS libraries were doing because we didn't use them. We were concerned with consistency, more than anything We went with camelCase because we liked that it was the same convention we followed in our JavaScript, AND it was easy to select stuff in the IDE. Even WITH there being a VSCode extension, I still wouldn't change my reasoning because that kinda breaks the guidance of, "least disruptive to the team." I wouldn't want to have a project that required some IDE extension to keep teammates productive the way they want. ALL THAT SAID, as I explained in the start of the guidelines, they are just that...guidelines. The goal is to be consistent and not have teammates present or future curse your name. So developers should really favor team cohesiveness over my opinions based on my specific experience.
- Vinnl 5y ago> Does a Test need it? > Use .qa Generally, I'd recommend trying to query elements in a test using accessible selectors, if possible. For example, look for the input[type=email] or button[aria-label~="Submit"]. That helps prevent people from forgetting to update or accidentally removing these often invisible properties. I'd especially recommend testing-library for this purpose, which allows you to easily query by e.g. role and the accessible name of an element: https://testing-library.com/ https://testing-library.com/
- the_other 5y agoThis battle was lost in my current employer’s codebase years before I joined. We have data-test-id for half the components. It makes me sad.
- paceaux 5y agoTo be totally honest, I originally didn't have any guidance around having a class name for .qa (this was a gist long before I made it a blog post and I'd been sharing the gist with teams for years). I had a boss point out that sometimes for [reasons] he would have to add selectors to things just for Selenium tests, and when that happened, he like using .qa because then it was obvious to him and anyone else it had to be deleted later. BTW, the _reason_ he had to add classnames was because we worked in enterprise content management and there were all sorts of situations where, for WHATEVER reason, we couldn't change the markup, or we could only modify the markup in VERY specific ways via the CMS. So finding a way to stick `qa` on an element was a more straightforward path than writing some ridiculous selector like `body > div > div > header ~ article:first-child` Suffice to say, YES, I agree that adding a class just so you can run a test is bad, but, we hit situations where we had to, and when that happened, it was worth while to have a convention for knowing how to identify classes that served just that purpose.
- llimos 5y agoAgree with most of this, but I think using "i" for the iteration index is ubiquitous enough that everyone knows it (or should learn it).
- eterm 5y agoI agree provided the following: Is the iterator un-used within the body of the loop to do more than address a collection? If it is actually used, it suggests that it's representing more than just an iterator and should be named appropriately. If it isn't used within the body of the loop then it's purely for the sake of iterating across a collection (or just looping a given number of times) and should be named i.
- JamesAdir 5y agoany thing similar for back end code - mainly databases and such?