Comments

Only comment things that have business logic complexity.

Comments are an apology, not a requirement. Good code mostly documents itself.

Bad:

  1. function hashIt(data) {
  2.   // The hash
  3.   let hash = 0;
  5.   // Length of string
  6.   const length = data.length;
  8.   // Loop through every character in data
  9.   for (let i = 0; i < length; i++) {
  10.     // Get character code.
  11.     const char = data.charCodeAt(i);
  12.     // Make the hash
  13.     hash = ((hash << 5) - hash) + char;
  14.     // Convert to 32-bit integer
  15.     hash &= hash;
  16.   }
  17. }

Good:

  2. function hashIt(data) {
  3.   let hash = 0;
  4.   const length = data.length;
  6.   for (let i = 0; i < length; i++) {
  7.     const char = data.charCodeAt(i);
  8.     hash = ((hash << 5) - hash) + char;
  10.     // Convert to 32-bit integer
  11.     hash &= hash;
  12.   }
  13. }

Don’t leave commented out code in your codebase

Version control exists for a reason. Leave old code in your history.

Bad:

  1. doStuff();
  2. // doOtherStuff();
  3. // doSomeMoreStuff();
  4. // doSoMuchStuff();

Good:

  1. doStuff();

Don’t have journal comments

Remember, use version control! There’s no need for dead code, commented code,
and especially journal comments. Use git log to get history!

Bad:

  1. /**
  2.  * 2016-12-20: Removed monads, didn't understand them (RM)
  3.  * 2016-10-01: Improved using special monads (JP)
  4.  * 2016-02-03: Removed type-checking (LI)
  5.  * 2015-03-14: Added combine with type-checking (JR)
  6.  */
  7. function combine(a, b) {
  8.   return a + b;
  9. }

Good:

  1. function combine(a, b) {
  2.   return a + b;
  3. }

Avoid positional markers

They usually just add noise. Let the functions and variable names along with the
proper indentation and formatting give the visual structure to your code.

Bad:

  1. ////////////////////////////////////////////////////////////////////////////////
  2. // Scope Model Instantiation
  3. ////////////////////////////////////////////////////////////////////////////////
  4. $scope.model = {
  5.   menu: 'foo',
  6.   nav: 'bar'
  7. };
  9. ////////////////////////////////////////////////////////////////////////////////
  10. // Action setup
  11. ////////////////////////////////////////////////////////////////////////////////
  12. const actions = function() {
  13.   // ...
  14. };

Good:

  1. $scope.model = {
  2.   menu: 'foo',
  3.   nav: 'bar'
  4. };
  6. const actions = function() {
  7.   // ...
  8. };