Code Monkey home page Code Monkey logo

guides's People

Contributors

calebeby avatar erikjung avatar gerardo-rodriguez avatar josh68 avatar lyzadanger avatar paul-hebert avatar spaceninja avatar tylersticka avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Forkers

hhy5277

guides's Issues

JS[l|h]int and convention enforcement

First question: jsHint vs. jsLint?

I prefer jsHint. I also know the maintainer which seems useful in some sort of useless way.

Here is my current default .jshintrc per my dotfiles repo:

{
    "predef": [
        "define",
        "require",
        "module",
        "process",
        "$"
    ],
    "globalstrict" : true,
    "camelcase"    : true,
    "eqeqeq"       : true,
    "indent"       : 2,
    "nonew"        : true,
    "quotmark"     : "single"
}

Some points of thought:

  • It likely makes sense to do .jshintrc-type enforcement on a project basis (not globally) to allow for differences in client requirements and as to not impose stuff on a user-wide level for people.
  • I have active personal leanings with regards to:
    • 2-space tabs. I can live with 4-space but odd numbers are not OK.
    • Single quotes.
    • camelCase var names

This jshintrc isn't particularly detailed, any other defaults we'd like to see covered?

Feel free to disagree with anything I have here so far (as long as you're prepared to engage in battle over the few things I highlighted above!). We also need to look at convention enforcement via jscs (or not) and things that are in .editorconfig's universe (FOR THE LOVE OF ALL THAT HAS EVER BEEN SPACES NOT TABS).

Discuss.
/cc @lharding @erikjung

Conventions for module requires

This is a specific one, and along the line of coding styles not convention enforcement.

@lharding had an interesting comment the other day about variable naming when requiring packages. One of the things we were finding hard to read in gulp code examples was when people would name required external modules something counterintuitive like count or source or concat.

One convention I see a lot is people dropping gulp- prefixes from required gulp modules so you end up with:

var data = require('gulp-data');

I can see both sides of this argument. data is a nice name, but embedded in lots of code an invocation off of data requires a cognitively-intense reference up to the top of the task/plugin to remind onesself what data is. This may not be an issue in short modules but as they get longer it can get cumbersome.

With respect to gulp stuff specifically, we could do something like

var gData = require('gulp-data');

though I admit I don't love the look of that, either. Hum.

Something to think about and discuss.

Git Guide: Update feature workflow

Update the workflow described for feature branches to better match what we've been recommending:

  1. create feature branch
  2. to update, merge master into your branch
  3. to merge feature to master, submit a PR
  4. when PR is approved, squash the commits

add a section on the dangers of force-pushing and rewriting history in a shared environment

Note: don't worry, I know this stuff isn't 100% settled. If I rewrite this, it'll go up as a PR so the team has a chance to review and make sure we all agree.

Git Guide: Add section on new repo config

Add a small section on how to configure a new repo, including:

  • disable wikis, forking, projects
  • enable read-only analysis & vulnerability alerts
  • add design & dev team with admin access (is that right, or should we make an admin team?)
  • enable master branch protection to require PR approvals
  • add PR template

Create "Modern" CSS Guide

I dig a lot about our current CSS guide, but there are a couple of new technologies that can (and should) challenge some of our conventions. We haven't had an opportunity to put this stuff into practice yet, but it's only a matter of time until IE11 is no longer a first-class optimization, freeing us up to pursue the next generation of awesome Cloud Four sites.

I'm including some open questions I have below that I'd love to resolve in a "modern" version of the guide for projects wanting to make the most of what the web has to offer. I'd love for us to discuss these at some point, and please feel free to mention other points to improve or iterate on.

Where does layout fit in?

Historically, layout in CSS has been pretty much the worst. Flexbox was an improvement, and gave us the ability to make nicer grid components. But with CSS Grid so well-supported, it's likely time to move a lot of layout logic from our markup back into stylesheets. (See this great Rachel Andrew post.)

So should these be handled like any component class? Should we be prefixing them like utilities, for example .l-Mosaic or .l-Spread? Or should we return to the idea of "section" CSS, perhaps only output on specific pages?

How can we make the most of custom properties?

Similarly well-supported in modern browsers are custom properties. If you haven't seen Lea Verou's talk on this, you absolutely should.

Put simply, custom properties are a zillion times better when they're handled in-browser. You can do fancier things with inheritance, you can manipulate them via JavaScript, and the resultant CSS will be tinier.

But does this completely negate the need for classic/precompiled/private CSS variables? Should we be going "all-in" and having everything be a property, or should we adopt an entirely unique syntax for those? Do we need standards for how we name and organize our properties?

Can we make animation approaches a first-class citizen of our stylesheets?

This is something I've been thinking about since seeing Sarah Drasner's talk on Animating Vue, and the power that comes with Vue's rather impressive animation and transition capabilities. We need to be pushing animation a bit more in our work, and right now our approach to this is woefully undocumented (and admittedly, not really fleshed out).

Add a Web Accessibility Guide

I'd like to take the lead on adding a Web Accessibility Guide that we can use as a reference on our projects.

I don't have a full vision yet, but some ideas that come to mind

  • resource links
  • tips
  • general guidelines with links to resources that go deeper on subjects
  • required vs strongly recommended vs optional/conditionally recommended buckets of advice/suggestions
  • what level of WCAG Guidelines are we following?
  • some example UX personas (each representing different types of disabilities)

πŸ˜„

JS Guide: Add caniuse.com links as reference

Interesting. On this note, is there any thought of adding comments about native support (thinking browsers), so that we don't end up relying on Babel or polyfills to use what should be more performant, future-friendly methods, but are actually being transpiled to something less performant, at least for some clients.

I realize this is a moving target and also very much a case-by-case thing, but even links to caniuse might be helpful.

Originally posted by @Josh68 in #35

Suggestion: General Rules - replace milliseconds with seconds

On the last two Cloud Four projects I've worked on, our CSS time units have deviated from what is specified in our guides.

Time values should be represented with the millisecond (ms) unit.

https://github.com/cloudfour/guides/tree/master/css#general-rules

@tylersticka recently shared these thoughts:

I recently switched to seconds for two reasons:
My brain understands how long a second is, it takes a little longer to translate to milliseconds.
My favorite JavaScript animation library uses seconds and I got tired of translating between them. πŸ˜…

I'd suggest updating our guides to reflect our current habits.

Introducing `rebase` to our daily workflow

As we get bigger and badder, I'm seeing a lot of chattery commits and a lot of redundant merge commits and merges overall. I'm interested in introducing a rebase policy, but wanted to get feedback. How do we explain the concept and how do we "sell" it, if it's something we'd like to encourage.

I think this recent post is written mostly in plain English, but might be long for those who aren't particularly interested. Thoughts?

JS Guide: NodeList prefer destructuring does not work OOB

https://github.com/cloudfour/guides/tree/master/javascript#34-arrays-from-iterables.

In our current project, using Babel with @preset/env and .browserlistrc of IE 11 > 1%, using querySelectorAll to create a NodeList and then using [...myNodeList] does not transform the list to an array. Instead, it transpiles to [].concat(myNodeList), which is just the NodeList as element 0 of a new Array.

For the browser support in question, Array.from(myNodeList) works as expected, including in IE 11.

Not sure whether there's a way to tweak this setup to make it work, but my recommendation is to make this rule flexible, if we keep it at all

/cc @calebeby @gerardo-rodriguez @spaceninja @Paul-Hebert

Git guide: Who owns merging PRs?

Something I realized today might not be represented in our Git guide: When a PR is approved, who merges it?

I always assumed the author is the one who merges, since I consider them the "owner" of the code. But a contractor recently read the guide and got the impression that the reviewer merges the code.


/CC @cloudfour/dev

Add editorconfig to code guide wiki

We've been talking about enforcing JS/editor conventions on a project-by-project basis (as in, not inflicting draconian requirements globally to everyone). I'm wondering what a good place to stick/manage those defaults would be. Specifically, items like:

  • .gitignore
  • .jshintrc
  • .jscs
  • .editorconfig

Any thoughts out there?

JavaScript Assignment: Intro Section

Hi @nicolemors !

This is a very first try to pull together a few introductory JS materials. What I'm thinking is that you can do the stuff defined here:

https://github.com/cloudfour/guides/blob/master/learning/javascript/README.md

which represents a sort of "first lesson" in intro JS, a conceptual introduction.

I'm not going to put a due date on this because part of the thing I'm trying to learn is how long this reasonably takes. Hard for me to assess, so I'm interested in getting your feedback on that. Here's what I'd like to do:

  • You try out the section, and think about the discussion questions and perform the exercises
  • You let me know when you're done
  • We schedule follow-up to discuss

I'm also interested in getting your feedback on things like:

  • Was any of this too hard or confusing?
  • What kind of schedule would feel right to you for working on chunks of material like this?
  • Did it take too long for a single chunk? Or was it not enough?

I'm not intending that this is completely stand-alone materialβ€”the follow-up discussion is part of the curriculum. But definitely let me know if any of it is just like "HUH?!"

You can use this issue thread to ask any questions, etc, as you go. We can resolve/close the issue when we feel like this section is "complete."

Add SVG Guide

Maybe after the internal meeting this week, we can rehash some of it into this area for discussion. I think it would be of value to document it for those of us who haven't done a great job keeping up with SVG in general.

Add a TypeScript Guide

As a dev team, we're moving towards TypeScript, but it's important to recognize that TypeScript isn't the most friendly to newbies (speaking from personal experience here). We should have a TypeScript guide that covers:

  • Why Cloud Four prefers TypeScript
  • Discusses any house standards (if we have any yet)
  • Points to some good "typescript 101" resources that are beginner-friendly.

Documents or Wiki?

Say we had a repository into which to put conventions, dev notes and protocols. Like, maybe this one. Would we want to maintain markdown files or use the Wiki feature in github? My hunch is the former (files). Discuss.

/cc @lharding @erikjung

Add section about documenting magic numbers

@spaceninja wrote this in a PR comment thread about why we prefer to convert "magic numbers" into variables. We should add a section rephrasing this to the CSS Guide:

Magic numbers in CSS files are a mystery. Why is it this particular value? What happens if I change it? Does it match anything else?

Turning your magic numbers into variables or custom properties is a form of documentation and safety checks:

By naming your number, you help explain what it means. $touch-target-size tells you at a glance what the number means and opens the door to reuse elsewhere.

It's also a form of safety check β€” if you set this value here and then it also gets used somewhere else but both locations are hard-coded, then a future dev doesn't know they need to update both if we want those sizes to match.

Thus, as a general practice, unless we have good reason, we convert almost all values to variables, custom properties, or design tokens.

Sometimes you really do have a special one-off magic number. "The component is sized at 137px wide because that's the only size that looks good". In those cases, when you don't need to reuse the value, then a descriptive comment explaining the source of the magic number is sufficient.

But in general, coming across a magic number with an unclear meaning and source is a red flag in a CSS file.

In almost every instance, I have found that what felt arbitrary made more sense when converted to a standard design token that already exists, or by documenting it so it could be reused.

In this case, your magic number is a very good one that can and should be reused elsewhere β€” minimum touch target size! That's a great case for making a design token, or at least a variable.

.editorconfig?

My current:

root = true
indent_style = space
indent_size = 2
charset = utf-8
end_of_line = lf
insert_final_newline = true

...and... πŸ‘Š ... fight!

(again, this likely enforced on a project-by-project basis?)

/cc @lharding @erikjung

Add Code Block example to Blog Patterns guide

Emerson

What's the best practice for showing blocks of code in a blog post? I didn't see it in our blog guides or the pattern library. <pre> + <code>?

Paul Hebert

You can use markdown so you can just use triple backticks to wrap code blocks

```css
/* some CSS */
```

```html
<!-- some HTML -->
```

```js
/* some JS */
```

Emerson

Ha. I didn't realize the wp editor understood markdown! Thanks

Derek Shirk

Not by default - as far as I know.

In addition to Paul’s example, you can also make use of the figure and figcaption elements if you want to caption your code examples.

JS Guide: return early if condition is not met

While reviewing a PR @gerardo-rodriguez recommended a pattern he picked up from @Josh68 that we should add to the JS Guide:

Instead of needing to wrap a larger block of code in an if conditional, how about returning from the method if conditions are not met?

start(options) {
  if (!this.element) {
    // Maybe even log a warning, if that makes sense?
    return;
  }

  // If you made it this far, continue on your merry way. :)
  // Also, hello, no extra indentations. ;) 
}

This pattern also helps remove the cognitive load of wondering why many lines later in this block of code why you are indented in so far.

* Scrolls down past `start()` method declaration so it's now offscreen *

"Why have we indented so far again?"

* Scrolls back up losing context of what I was looking at * 

"Oh right, we live in a conditional `if` statement"

* Pauses... *

* Starts scrolling back down *

"Where was I again?"

πŸ˜‰

Branch naming from `feature_all_the_things` to `feature/all-the-things`

I'd like to bring forth a proposal that we revise our Git guide to suggest a different naming convention for our Git branches.

Our Git Guide states:

Prefix the branch name with something meaningful, for example:

  • feature-make_the_thing_better
  • bug-the_thing_is_broken
  • cleanup-rename_all_the_files

I wholeheartedly agree with the "prefix the branch name with something meaningful" but would like to propose we change the naming convention to this instead:

  • feature/make-the-thing-better
  • bug/the-thing-is-broken
  • cleanup/rename-all-the-files

This lends itself to a much nicer organization when viewing as directories as well as any Git GUI apps:

screen shot 2018-07-11 at 11 14 41 am

Another benefit is it lends itself to this type of organization as well, when/if needed:

  • users/username/description
  • users/username/workitem
  • bugfix/description
  • features/feature-name
  • features/feature-area/feature-name
  • hotfix/description

I've now been using this naming convention in my current project for a while and really do like how easy it is to organize my branches by directories. I invite you to experience this with me as well. πŸ˜ƒ

@cloudfour/dev @cloudfour/design Thoughts?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.