Coding Standards at Cognitive

Overview

We continuously improve the engineering process at CognitiveClouds to increase the speed at which we develop new features and products while maintaining our developers' code's quality and extensibility. We train engineers at Cognitive to follow the coding standards for the languages and technologies they implement for customers. This post is a guide we use to teach new engineering hires about our process, so everyone is on the same page when it comes time to complete a code review, product maintenance, or a knowledge transfer.

Best Practices

We ask all engineers to follow these best practices when developing new products and extending existing software for customers.

Design-Driven Development

• Our design team engages with our customer and translates their business requirements into visual design assets
• Designers follow Visual and UX design standards for the target platform(s)
• Build clickable prototypes in Figma or Invision
• Get final approval from the customer
• Our developers are involved in the process
• Review UX for feasibility
• Recommend changes before showing the design assets to customers
• Our developers don't write code until our customer signs off on the design

Dev Ops Setup

• Obtain an account for our customer's cloud infrastructure on AWS, Google Cloud Platform (GCP), or Microsoft Azure
• Setup Jenkins CI/CD pipeline before starting any implementation
• When the product matures, setup Development, Staging, and Production environments
• Set all configurations for the application on the instance in an environment configuration file
• Use Key/Value pairs to set the configurations
• Keys are the same in this file on all three environments, but the values are specific to each environment
• Credentials and URL for Sendgrid or any other notification service Stripe keys, Payment Gateway credentials/keys for each environment
  
• Dev, QA, Prod URLs
• Database/RDS credentials
• Other third-party services integrated with the product

Agile Development

• Our project manager organizes user stories into 2-week sprints
• Developers must follow the coding standards mentioned in this document
• Complete three code reviews
• Self-review
• Another developer does a peer review
• After implementing changes based on the reviewer's comments, a different
• developer reviews the code again
• The developer implements the feedback from the final review
• The developer implements unit test cases
• Code coverage must be at least 80%
• The developer must get approval to deploy to the staging environment if the code coverage is less than 80%

Quality Assurance

• Complete a design audit once before QA begins and a second time after QA tests 60% of the product features
• QA starts their involvement at the end of the design phase
• Test plans are written and reviewed by developers
• QA needs to follow QA best practices for
• Functional Tests
• Integration Tests
• System Tests
• Smoke Tests
• Interface Tests
• Regression Tests

General Software Development Best Practices

• Follow the don't repeat yourself (DRY) principle
• Complete a code review before making a pull request
• Use a linter to make your code easier to review, and follow strict linting rules to helps you write clean code
• Split code into multiple small functions that each have a single task
• Create numerous utility files to remove duplicate code from multiple files
• Componentize code into multiple files instead of writing one large file
• Name files based on the job they perform
• Use variable and function names that make your code self-commenting and document complex functions with comments
• Write test cases and keep them in sync with the files they're testing

React.js

• Name UI components with PascalCase
• Example: LoginScreen.js
• Name helper files with camelCase
• Example: commonUtils.js
• Name folders with camelCase
• Example: components
• Name CSS files with PascalCase
• Name global CSS files with camelCase and place them in global.css
• Example: LoginScreen.css (components), global.css (global styles)
• Use kebab-case for CSS class names because it follows the convention used by most CSS framework classes
• Name test files the same as component or non-component files
• Example: LoginScreen.test.js, commonUtils.test.js
• Place all CSS files in one common folder
• Avoid inline CSS and create CSS classes when two or more CSS attributes exist
• Separate all service calls into individual files
• Destructure props to make code clean and more maintainable
• For example (async function authenticate({ user_id, token }) {})
• Use useReducer once useState becomes complex
• Use Hooks as much as possible, and even for redux related operations => useSelector and useDispatch
• Put imports in order
• React import
• Alphabetical order (Library, Absolute, and Relative imports)
• Import * as
• Import ‘./.
• Use empty lines to separate each import kind to make them clean and easy to understand for all components and 3rd-party libraries
• Use index.js for each folder export and don't repeat import names

Angular

For Angular, we don't need to reinvent the wheel. We've followed Angular's guidelines for a long time, and they've worked well for us.

https://angular.io/guide/styleguide

Node.js

Naming conventions:

• Use lowerCamelCase for variables, properties, and function names
• Use UpperCamelCase for class names
• Use UPPERCASE for Constants
• Use descriptive function and variable names
• Make file names lowercase and include underscores or dashes if needed, but don't add other punctuation
• Module import names should be lowerCamelCase

Indentations:

• Indent class literals as blocks
• When declaring a function, the function's body is indented two spaces more than the preceding indentation depth
• As with any other block, indent the contents of a switch block +2
• 'Requires' always at the top to show files dependencies
• Semicolons are required
• Every local variable declaration declares only one variable
• Delimit ordinary string literals with single quotes ('), rather than double quotes (")
• Declare all local variables with either const or let
• Use const by default, unless you're reassigning a variable
• Never use the var keyword
• Require modules by folders instead of files only
• Use === operator as both variables must be of the same type to come out as equal
• Use async/await instead of callbacks to avoid complicated nesting
• Send the appropriate error status along with the errors
• Use built-in Error Object instead of throwing strings as errors

Python

Follow this well-documented guide on Python coding standards: https://www.python.org/dev/peps/pep-0008/

• Use snake_case for variables, properties, and function names
• Use UpperCamelCase for class names
• Use descriptive function and variable names
• File names must be all lowercase and may include underscores or dashes, but no additional punctuation
• Module import names should be lowercase
• Limit all lines to 79 characters
• Use dictionary-based function calls and mapping to achieve O(1) time complexity
• Have a good understanding of multithreading, multiprocessing, and global interpreter lock
• Use decorators and middleware when performing the same task for multiple actions