Skip to content

Engineering Practices

Jump to bottom
Song Zheng edited this page Jun 19, 2022 · 25 revisions

Intro

Best practice to follow for engineering team

Development

  • All of your commits must be tagged with an issue number. If your commit fixes / resolves an issue, make sure it says in your commit. For example:
    • git commit -m 'close #42 - adds username validation for length'
  • You must break down an issue into multiple PRs if the issue is complex.
    • git commit -m 'update #42 - creates new service function to create login session'
  • Don't have huge PRs -- if you are making a component for example, then make that component and its accompanying stories for one PR, and implement it onto the website the next PR.
  • Do not lower 100% Code Coverage
  • Do not use a anchor tags unless it is to a different domain. Must use Link component for client side rendering.
  • Frontend - When creating new routes, always use lowercase. Don't use camel case since the route can be case-sensitive (i.e. use https://www.c0d3.com/sendemail instead of https://www.c0d3.com/sendEmail)
  • Storybook - If you build a reusable component, please create a component with all the possible states in your component, so other devs know how to use that component.
  • In the backend - On invalid responses, always throw. Example signup resolver
  • GraphQL - use yarn generate when modifying code inside the /graphql/ folder to generate TS code to be used with GraphQL front-end
    • Local server must be running on port 3000
  • On front end, instead of using throw, use Sentry.captureException instead.
  • On the back end, use internal logger function to log error to sentry
  • Create a Design Doc for any large or complex issues or features. Need to figure out why you need one? Read about Design Docs at Google. List of design docs

FrontEnd

React

CSS

  • Use variables in your CSS instead of hard coded values. The first benefit of using variables is that if we need to change the background or text color of the page, we just change the variable (alot of sites do holiday themeing). Another benefit is that it prevents us from getting to a place where we have different colors for the same text.
  • Do NOT Copy auto generated css from design tool, because it includes alot of unnecessary properties that are already set by default. Copying auto generated css will cause our CSS to be very bloated and unmanageable. Example
  • Padding and margins for css should use px so that UI elements look consistent across all devices and screen sizes. Example of wrong usage
  • CSS classnames - follow BEM Syntax. In a nutshell, .block--modifier__element
    • Examples: .person--female__hand and .person__hand--left

Testing

  • when you run npm run test, there's a column called Uncovered Lines that tells you which lines are not tested
  • When writing tests, please write out the actual changes instead of toMatchSnapShot(). If we get lazy and use toMatchSnapShots all over the place, our tests slow down significantly and when we update a common component like the AppNav, there would be hundreds of snapshots to update.
    • Example of what you should not do. In that example, it is taking snapshots repeatedly to make sure search filters are working. Instead, it is better to select the results and expect the number of results to be X.
  • Always use expect.assertions to verify that all the assertions (e.g, expect(1).toBe(1)) are called during a test.
    • If async code is being used, there's only one assertion, and the assertions count is more than 1. Use expect.hasAssertions.

Learning

Clone this wiki locally