Go to the profile of Joey Guerra
Joey Guerra
My goodness it’s dark in here.

Coding and Code Review Guidelines

In order to reuse code, it must pass the teams measurement of readability and discoverability.

If it is determined that a particular module or code is not reusable, it should be refactored into a “legacy code” area in preparation for deprecation so that it is decoupled from the rest of the codebase.

If you’re making changes to an existing function, you should make a concerted effort to make it testable by a unit test case. Write it first before you start the refactoring journey. It’s likely to be a long one.

Pair program. It creates an environment where code review happens as part of the process.

Discuss if the code follows the SOLID principles.

If code is not formatted and adequately indented such that it’s difficult to read, format it before continuing.

Consider creating a module when adding new functionality. Practice TDD while coding it.

Upon having to modify existing functionality where the code is not in it’s own module, consider creating a new module and moving that code into it.

Variable, module, and function naming is one of the main characteristics that will make code either readable or not. It’s a powerful tool to communicate and document. Consider your names carefully. Follow these guidelines when naming something. These are my intpretation of what Uncle Bob talks about in his Clean Coder series.

  • Reveal and communicate your intent. If you’re compelled to write a comment, you haven’t sufficiently revealed it’s intent.
  • Functions and methods should be verbs or verb phrases, unless it returns a boolean, in which case it should read like a predicate (e.g. shouldShow(), isActive());
  • Variables should be nouns, unless they’re booleans which should be predicates.
  • Enums should be adjectives.
  • Variables: the longer the scope, the longer the name of the variable.
  • Variables: the shorter the scope, the shorter the variable name.
  • Functions and Classes: the longer the scope, the shorter the name. The shorter the scope, the longer it should be.
  • Use short names for public APIs so they are convenient to use.
  • Long names for functions/methods that are private.
  • Avoid disinformation — saying something other than you mean. Correct it if you recognize it.
  • If the meaning of a function, variable or class have changed, changed the name to reveal it’s intent.
  • Use pronounceable names. Read the code out load as a test. Does it sound right?
  • Avoid encodings like hungarian notation in the names. E.g. Account is better than IAccount.
  • Write code that a human can understand.

Functions do 1 thing, extract till you drop.

  • Functions should be small, ~ 4 lines of code. Making functions small will help everyone.
  • Well named functions help the developer navigate the code base.
  • If a function is long, consider creating a class to put those functions. Classes hide in long functions.
  • Function signatures should be small, 3 or fewer parameters.
  • Do not pass booleans into functions. They’re presence indicate that the function does more than 1 thing.
  • No output arguments in function signatures.
  • Organize methods according to step down principle (public methods at top).
  • Consider replacing switch statements with polymorphism.