A series of best practices for JavaScript projects

• Checkout a new feature/bug-fix branch

  git checkout -b <branchname>Copy the code

• Make Changes

  git add
  git commit -m "<description of changes>"Copy the code

• Sync with remote to get changes you’ve missed

  git checkout develop
  git pullCopy the code

• Update your feature branch with latest changes from develop by interactive rebase (Here is why)

  git checkout <branchname>
  git rebase -i developCopy the code

• If you don’t have conflict skip this step. If you have conflicts, resolve them and continue rebase

  git add <file1 > <file2 >. git rebase --continueCopy the code

• Push your branch. Rebase will change history, so you’ll have to use -f to force changes into the remote branch. If someone else is working on your branch, use the less destructive --force-with-lease (Here is why).

  git push -fCopy the code

• Make a Pull Request.
• Pull request will be accepted, merged and close by reviewer.
• Remove your local feature branch if you’re done.

• Separate the subject from the body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why as opposed to how

• Use this template for README.md, Feel free to add uncovered sections.
• For projects with more than one repository, provide links to them in their respective README.md files.
• Keep README.md updated as project evolves.
• Comment your code. Try to make it as clear as possible what you are intending with each major section.
• If there is an open discussion on github or stackoverflow about the code or approach you’re using, include the link in your comment,
• Don’t use commenting as an excuse for a bad code. Keep your code clean.
• Don’t use clean code as an excuse to not comment at all.
• Comment even small sections of code if you think it’s not self explanatory.
• Keep comments relevant as your code evolves.

• Depending on project size, define separate development.test and production environments.
• Load your deployment specific configurations from environment variables and never add them to the codebase as constants, look at this sample.
• Your config should be correctly separated from the app internals as if the codebase could be made public at any moment. Use .env files to store your variables and add them to .gitignore to be excluded from your code base because of course, you want the environment to provide them. Instead commit a .env.example which serves as a guide for developers to know which environment variables the project needs. It is important to remember that this setup should only be used for development. For production you should still set your environment variables in the standard way.
• It’s recommended to validate environment variables before your app starts. Look at this sample using joi to validate provided values.

• Have a test mode environment if needed.
• Place your test files next to the tested modules using *.test.js or *.spec.js naming convention, like module_name.spec.js
• Put your additional test files into a separate test folder to avoid confusion.
• Write testable code, avoid side effects, extract side effects, write pure functions
• Don’t write too many tests to check types, instead use a static type checker
• Run tests locally before making any pull requests to develop.
• Document your tests, with instructions.

• Organize your files around product features / pages / components, not roles

Bad

. ├ ─ ─ controllers | ├ ─ ─ the product. The js | └ ─ ─ the user. The js ├ ─ ─ models | ├ ─ ─ the product. The js | └ ─ ─ user. JsCopy the code

Good

. ├ ─ ─ the product | ├ ─ ─ index. The js | ├ ─ ─ the product. The js | └ ─ ─ the product. The test. The js ├ ─ ─ the user | ├ ─ ─ index. The js | ├ ─ ─ the user. The js | └ ─ ─ user.test.jsCopy the code

• Place your test files next to their implementation.
• Put your additional test files to a separate test folder to avoid confusion.
• Use a ./config folder. Values to be used in config files are provided by environment variables.
• Put your scripts in a ./scripts folder. This includes bash and node scripts for database synchronisation, build and bundling and so on.
• Place your build output in a ./build folder. Add build/ to .gitignore.
• Use PascalCase' 'camelCase for filenames and directory names. Use PascalCase only for Components.
• CheckBox/index.js should have the CheckBox component, as could CheckBox.js, but not CheckBox/CheckBox.js or checkbox/CheckBox.js which are redundant.
• Ideally the directory name should match the name of the default export of index.js.

• Use stage-1 and higher JavaScript (modern) syntax for new projects. For old project stay consistent with existing syntax unless you intend to modernise the project.
• Include code style check before build process.
• Use ESLint – Pluggable JavaScript linter to enforce code style.
• We use Airbnb JavaScript Style Guide for JavaScript, Read more. Use the javascript style guide required by the project or your team.
• We use Flow type style check rules for ESLint. when using FlowType.
• Use .eslintignore to exclude file or folders from code style check.
• Remove any of your eslint disable comments before making a Pull Request.
• Always use //TODO: comments to remind yourself and others about an unfinished job.
• Always comment and keep them relevant as code changes.
• Remove commented block of code when possible.
• Avoid js alerts in production.
• Avoid irrelevant or funny comments, logs or naming (source code may get handed over to another company/client and they may not share the same banter).
• Write testable code, avoid side effect, extract side effects, write pure functions.
• Make your names search-able with meaningful distinctions avoid shortened names. For functions Use long, descriptive names. A function name should be a verb or a verb phrase, and it needs to communicate its intention.
• Organize your functions in a file according to the step-down rule. Higher level functions should be on top and lower levels below. It makes it more natural to read the source code.

• Avoid client-side console logs in production
• Produce readable production logging. Ideally use logging libraries to be used in production mode (such as winston or node-bunyan).

Follow resource-oriented design. This has three main factors: resources, collection, and URLs.

• A resource has data, relationships to other resources, and methods that operate against it
• A group of resources is called a collection.
• URL identifies the online location of a resource.

• /users a collection of users (plural nouns).
• /users/id a resource with information about a specific user.
• A resource always should be plural in the URL. Keep verbs out of your resource URLs.
• Use verbs for non-resources. In this case, your API doesn’t return any resources. Instead, you execute an operation and return the result to the client. Hence, you should use verbs instead of nouns in your URL to distinguish clearly the non-resource responses from the resource-related responses.

GET /translate? text=Hallo

Sub resources are used to link one resource with another, so use sub resources to represent the relation. An API is supposed to be an interface for developers and this is a natural way to make resources explorable. If there is a relation between resources like employee to a company, use id in the URL:

• GET /schools/2/students Should get the list of all students from school 2
• GET /schools/2/students/31 Should get the details of student 31, which belongs to school 2
• DELETE /schools/2/students/31 Should delete student 31, which belongs to school 2
• PUT /schools/2/students/31 Should update info of student 31, Use PUT on resource-URL only, not collection
• POST /schools Should create a new school and return the details of the new school created. Use POST on collection-URLs

• 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
• 401 Unauthorized indicates that the request lacks valid credentials needed to access the needed resources, and the client should re-request with the required credentials.
• 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason.
• 404 Not Found indicates that the requested resource was not found.
• 406 Not Acceptable A response matching the list of acceptable values defined in Accept-Charset and Accept-Language headers cannot be served.
• 410 Gone indicates that the requested resource is no longer available and has been intentionally and permanently moved.

• Provide total numbers of resources in your response
• The amount of data the resource exposes should also be taken into account. The API consumer doesn’t always need the full representation of a resource.Use a fields query parameter that takes a comma separated list of fields to include:

  GET /student? fields=id,name,age,classCopy the code

• Pagination, filtering and sorting don’t need to be supported by default for all resources. Document those resources that offer filtering and sorting.

To secure your web API authentication, all authentications should use SSL. OAuth2 requires the authorization server and access token credentials to use TLS. Switching between HTTP and HTTPS introduces security weaknesses and best practice is to use TLS by default for all communication. Throw an error for non-secure access to API URLs.

It’s difficult to perform most attacks if the allowed values are limited.

• Validate required fields, field types (e.g. string, integer, boolean, etc), and format requirements. Return 400 Bad Request with details about any errors from bad or missing data.

• Escape parameters that will become part of the SQL statement to protect from SQL injection attacks

• As also mentioned before, don’t expose your database scheme when naming your resources and defining your responses

The server should never assume the Content-Type. A lack of Content-Type header or an unexpected Content-Type header should result in the server rejecting the content with a 406 Not Acceptable response.

• Fill the API Reference section in README.md template for API.
• Describe API authentication methods with a code sample
• Explaining The URL Structure (path only, no root URL) including The request type (Method)

For each endpoint explain:

• URL Params If URL Params exist, specify them in accordance with name mentioned in URL section

Required: id=[integer]
Optional: photo_id=[alphanumeric]
Copy the code

• If the request type is POST, provide a working examples. URL Params rules apply here too. Separate the section into Optional and Required.
• Success Response, What should be the status code and is there any return data? This is useful when people need to know what their callbacks should expect!

  Code: 200
  Content: { id : 12 }
  Copy the code

• Error Response, Most endpoints have many ways to fail. From unauthorised access, to wrongful parameters etc. All of those should be listed here. It might seem repetitive, but it helps prevent assumptions from being made. For example

  {
      "code": 403."message" : "Authentication failed"."description" : "Invalid username or password"
  }   Copy the code

Make sure you use resources that you have the rights to use. If you use libraries, remember to look for MIT, Apache or BSD but if you modify them, then take a look into licence details. Copyrighted images and videos may cause legal problems.

Sources: RisingStack Engineering, Mozilla Developer Network, Heroku Dev Center, Airbnb/javascript Atlassian Git tutorials