Skip to main content

General Principles

The following is a list of language-agnostic development rules and principles that should be followed when working within any Rizing development project.

note

Rules related to specific languages can be found in their respective section (see catalog).

📚 Philosophy​

Rizing's code base is built with the philosophy that less code is better code. We aim to write simple and concise software that is easily readable, consistent, and re-usable.

tip

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

Not every principle herein has to be strictly followed, and even fewer will be universally agreed upon. These are guidelines and nothing more, but they are ones codified over many years of collective experience by the authors of Clean Code.

📜 General Principles​

Below are a set of general principles that should be followed when working within any Rizing development effort.

  1. Be consistent
  2. Self documenting code
  3. Automate anything that can be automated
  4. If you see an issue (even if it's not yours) fix it or make a ticket to address it later
  5. Always follow Clean Code principles

The following is a set of general principles inspired by quotes directly from Clean Code.

LeBlanc's Law​

"Later equals never"

If the code can be cleaned up now, do it now - because later never happens.

Keep Code Clean​

"The only way to make the deadline — the only way to go fast — is to keep the code as clean as possible at all times."

Using the excuse that you can't write clean code because you don't have the time is not a valid argument.

Be Intentional​

"Clean code always looks like it was written by someone who cares"

Writing clean code doesn't just happen. You have to intentionally be explicit and thoughtful.

Be Proactive​

"Leave the campground cleaner than the way you found it."

You are not ONLY responsible for code you wrote, but for the system as a whole. If you see something wrong, fix it.

Writing Skills​

"Make the code read like a top-down set of paragraphs."

"Master programmers think of systems as stories to be told rather than programs to be written."

Clean code should not have to be analyzed, but rather read like a book. Readers should not have to do mental math or calculations, rather they should be able to read variable and function names and understand what is happening.

Self Documenting​

Comments should explain why not what. What your code is doing, should be self-evident.

"Every time you write a comment, you should grimace and feel the failure of your ability of expression."

"Don’t comment bad code—rewrite it."

Code should be self documenting, meaning it can be clearly read like a book or set of instructions. If it cannot, then there is a failure in the code to express the intent.

One Word per Concept​

"Use the same concept across the codebase."

FetchValue() vs GetValue() vs RetrieveValue()

If you are using fetchValue() to return a value of something, use the same concept; instead of using fetchValue() in all the code, using getValue(), retrieveValue() will confuse the reader.

dataFetcher() vs dataGetter() vs dataFetcher()

If all three methods do the same thing, don't mix and match across the code base. Instead, stick to one.

FeatureManager vs FeatureController

Stick to either Manager or Controller. Again, consistency across the codebase for the same thing.

Don't Repeat Yourself (DRY)​

"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system."

At its simplest level, this basically means that you should aim to reduce the amount of duplicated code that exists.

Clarity is King​

"One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand."

📑 SOLID Principles​

Rizing development guidelines and principles are based on Clean Code and subsequently SOLID principles.

SOLID is the mnemonic acronym introduced by Michael Feathers for the first five principles named by Robert Martin, which meant five basic principles of object-oriented programming and design.

It is highly recomended that you read the book Clean Code and fully understand the concepts and ideas herein. You can review the Clean Code summary documentation and visualizations here.

🛡 Code Reviews​

All code that makes it into any production system must go through a code review process (triggered by a Pull Request). Once bugs are introduced into a codebase it is exponentially harder to find and get rid of them. The code review offers a last opportunity to stop bugs from being introduced into the codebase. It is a core requirement of all team members to participate in, and contribute to, the code review process.

Humorous image of software quality estimation as a count of how many expletives you shout when reading code

Code Review Checklist​

  • Is the PR linked to an issue?
  • Does the functionality work per the specifications?
  • Does the code meet the coding standards guidelines?
  • Do all linting and automated tests pass?
  • Does new functionality have adequate test coverage?
  • Does new functionality have adequate documentation coverage?

🔧 Tooling & Automation​

"Anything that can be automated, should be."

The success of Rizing development operations depend on the ability to scale development efforts and benefit from standard and predictable behavior and code. As a result, tooling should be implemented to automated anything that can be automated, whenver possible. Automations help keep things consistent and reduce repetative tasks. An example of such tools include; automatically running code formatters on save, git hooks, and pipeline build processes.

📝 Modifying Rules​

All coding standards documentation and rules are kept and maintained via Git, any recommended changes or enhancements to any standards should be made through a Pull Request.