Forem: Tatjana

The thing with abbreviations - Programming Principles

Tatjana — Thu, 19 Sep 2024 08:15:16 +0000

Developers like to keep things short. We need to save time wherever possible, and that's why we also favor abbreviations. Abbreviations are common and useful in programming principles, but they are often not very descriptive. Here is an incomplete list of common programming principles abbreviations that you should have encountered at least once in your programming career:

KISS (Keep it simple, stupid!)

KISS is the abbreviation of "Keep it simple, Stupid" or sometimes "Keep it simple and smart" or "Keep it simple and short". The principle encourages reducing the complexity of the code(-base) as much as possible. Simpler code is easier to read, maintain and test. While it may sound straightforward, simplifying code effectively takes hard work. Fortunately, many of the other programming principles, like DRY and YAGNI, support the KISS principle.

DRY (Don’t repeat yourself)

DRY stands for "Don't repeat yourself", which, as the name suggests, aims to eliminate redundancy. However, does this mean you should never have the same code twice? Not necessarily. A good guideline is the Rule of Three: if you're writing the same code for the third time, it's probably time to de-couple, refactor or abstract the problem. Consider future maintenance — do you really want to update multiple code sections when something changes?

By the way, did you know that there is also the opposite of DRY: WET - Write Everything Twice?

YAGNI (You Aren’t Gonna Need it)

YAGNI means "You Aren't Gonna Need it", which in any case does not apply to this principle. When developing a feature, it can be tempting to add extra functionality for potential future use. You might anticipate future needs or create interfaces with additional functions, just in case. YAGNI advises focusing solely on what is needed right now. Plans often change, and what seems necessary today may be irrelevant tomorrow. Design for adaptability, but don't build more than what's required.

SOLID

The SOLID principles are a set of five principles aimed at making software designs more understandable, flexible, and maintainable. They were developed by Robert C. Martin, Bertrand Meyer, and Barbara Liskov, with the acronym popularized by Michael Feathers. Each letter stands for a specific principle. Even though the principles talk about classes, they can also be applied to frontend development - especially for components. In frontend development, applying SOLID helps create more modular, scalable, and maintainable components.

S - Single Responsibility Principle

"There should be only one reason for a class to change. In other words, every class should have only one responsibility."

If you have a component for a product overview ProductOverview, this component should not include getting the products from a backend. Better have a service or another component like ProductFetcher getting the data.

O - Open Closed Principle

"Classes should be open for extensions but closed for modifications."

For instance a BaseButton button component defines basic styles and behaviour. When creating variations like PrimaryButton or a SecondaryButton, they extend the base component without changing it's core logic.

L - Liskov Substitution Principle

"If a base class is a subtype of a super class, it should be possible to replace the super class with the base class without disrupting the behavior of the program."

In other words, this means the base class should be usable wherever you expect the super class.

Coming back to the button example, if you have a IconButton that extends a Button component. The IconButton could be used everywhere where the Button is implemented.

I - Interface Segregation Principle

"Interfaces should be split such that clients only need to know about methods that are of interest to them. No client should be forced to depend on methods it doesn't use."

If you have a component that needs to have specific data like user information. Don't pass a user object with all possible data to the component, but just the values the component needs like username and name.

D - Dependency Inversion Principle

"High-level modules should not depend on low-level modules; both should depend on abstractions."

API calls for example should be wrapped in services, so whenever the interface changes the component is not effected by that.

TSR (The Scout Rule)

Though I call this TSR, "The Scout Rule", there isn’t any official abbreviation for it. In fact, it's referred to as 'The Boy Scout Rule' by Uncle Bob. Regardless of the name, I think it’s an excellent principle.

The rule comes from the Scouts' motto: “Always leave the campground cleaner than you found it”. Applied to coding, it means leaving the codebase better than it was. Whenever you touch the code, take a moment to improve it: re-format the file, remove unused dependencies or css styles or refactor a complicated function. Regularly tidying up will make your codebase more readable and maintainable over time.

(Commit) Message in a bottle

Tatjana — Tue, 20 Aug 2024 12:00:40 +0000

Imagine: You just finished writing the perfect piece of code. Spending hours - probably days - making it shiny and clean. Following all the best practices. Even adding some documentation! And you know. This code is ready to enter the world. You lean back. Ready to commit your code. Ready to commit you code? Oh no... you need a commit message... How to summarize the world changing code you just created? The blinking cursor jeers you. Your head is blank. It feels like the world is waiting for your genius commit message. Your fingers move carefully and slowly across the keyboard. You start typing. Quickly. "new stuff". Commit. Push. And that's it.

Can you relate to that? Than you're probably not alone.

Why good commit messages matter

But well-written and meaningful commit messages can be of advantage. They help you, future-you and other developers to understand what and how you built your project. And they help you to work faster. If you have a consistent structure of commit messages, you can automatically create changelogs or software versions. You could also automatically trigger build and publish processes.

Conventional Commits

Luckily there already is a specification that helps to create better commit messages: Conventional Commits. Sometimes this specification is also referred to as semantic commits.

Structure of Conventional Commits

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Example:

feat(auth): add new authentication role

Add role of 'Witch' - a role that magically gets access to every page

Refs: TICKET-1337

Types

The type is mandatory and gives a first hint on what the commit contains. The following types are defined in the Conventional Commit:

feat - introducing/removing a new feature
fix - repairing a bug
build - adding/updating build system or external dependencies
chore - updating internal code, no production code change (e.g. initial commit, change .gitignore)
ci - changing CI configuration
docs - adding/updating documentation
style - updating the code without changing the meaning (formatting, white-spaces, &c.)
refactor - refactoring code
perf - improving performance
test - adding/updating tests

Sidenote: If you're more the picture-type, you could think about using gitmoji as types.

Scope

The scope is optional. It gives more information about where in the code the change is located. This could be a topic like authentication or even a file like auth-roles.ts.

Description

In addition to the type, the description is also mandatory. It is in an on point summary of what the commit contains.

Body

The body is reserved for providing additional contextual information like a motivation or a more detailed description of the commit. The body is optional.

Footer

The footer is also optional. Each commit message can have various footers. Each footer starts with a word token, followed by either a : (or # separator) and afterwards a string.

Footer tokens can be e.g. Refs, Closes, Acked-by

If you want to add a ticket number to your commit message. You can use the footer for that.

Breaking Change

Breaking Changes can be introduced in two ways. Either with an ! after the scope and right before the : or with a footer that has BREAKING CHANGE as a token and is followed by :.

Tense of description/body-texts

The Conventional Commit specification doesn't include rules about the tense for the description or the body text.

Normally you find the texts in simple present or in the will-future.

For the simple present form imagine that the text would start with The commit. The describing verb then would be something like adds.

feat(auth): adds new authentication role

In the will-future form the text would start with The commit will. The describing verb then would be something like add.

feat(auth): add new authentication role

I personally prefer the will-future form. But I also think it's something where you can adapt to the majority of the team.

Conventional Commit in IntelliJ

If you're using an IntelliJ product and you want a little bit support with your conventional commit message. I can recommend the Conventional Commit plugin from Edoardo Luppi. See
https://plugins.jetbrains.com/plugin/13389-conventional-commit