A Transparent Sfotware Piece

Transparency is an expression used in different aspects and refers to different meanings based on the context in which it is used, but besides all these meanings, it has one property that never changes, which is clarity and purity.

You may find transparency terms mentioned in software houses while dealing with clients; in many cases, it means that the software your company is building and its functionalities should be clear, obvious, trustable, and testable. The term doesn’t stop at this point; it also means that the company should be clear about deadlines, project milestones, and the quality of delivery. Although this is a very interesting topic, this is not what I mean by transparency from a software engineer's standpoint; the meaning of “transparency” in software goes beyond that!

Transparency In Functional Programming

It’s a good thing to take a look at what transparency means in functional programming because its concept is very close to what I mean.

Among all functional programming principles, there are two important concepts in functional programming:

• purity I will talk about purity here in a short way, but you can search for it for more information. Purity means that each function is written in functional programming so that every time you give that function the same input, it should return the same output; it doesn’t have something in the middle that can change the result or return an undetermined result “side effect”. Purity is also meant to make the function self-contained without being affected by or affecting the outside world.
• transparency Transparency is usually shipped with purity; if the code is pure, which means we are able to expect its output, then we can replace that code with its result without affecting the behaviour of the programme. For example, suppose we have a function that calculates the total price based on the given taxes.

func calculateTotalPrice(basePrice float64, taxRate float64) float64 {
    totalPrice := basePrice + (basePrice * taxRate)
    return totalPrice
}

totalPrice := calculateTotalPrice(50, 0.2)

So basically, if we wanted to replace the call of this function with the result, this would not affect the programme execution as follows:

totalPrice := 50 + (50 * 0.2)

The Transparency Principle in Software Engineering

Transparency is not meant for functional programming only, it’s a very good principle that should be followed in the whole software cycle. Transparency is not a specific design pattern you can follow; it’s a principle and term that consists of multiple patterns and paradigms that help you build transparent software.

Transparency starts with defining variables

Defining variables is considered the basis of any software project. You need to define variables that represent the data type you will work with, and these variables should be transparent at different levels

• Transparent Data Type:
  It’s very important to define the data type for each variable and not change that data type to make your programme transparent. This may seem normal in static-typed languages like Java, C#, Rust, and others, but in dynamic languages like Javascript, this is very important because the language itself allows these weird behaviours, which will lead later to untransparent code.

• Transparent Data Structure:
  data structure Transparency means you have a well-defined structure that shapes programme data. It doesn’t matter if it’s a database, an internal variable, or data being transferred over the network to other services; you should always have a transparent structure for data so that anyone can understand what these data refer to. Unstructured data may let you feel like you are free and can store whatever you want, but this will lead you to a big miss after a while if there is not at least a general structure for the data.

• Namings:
  The best way to give a description for something is to make that thing self-descriptive; this could be achieved by choosing the most valid and proper names for the business that the software serves. A very good thing could be included here, which is DDD’s “ubiquitous language” which leverages using a common language between business experts and developers, and that language should be represented in the code as well.

Transparent Code Structure

The code structure is another part of the software development process where you can achieve transparency. The meaning of transparent code structure is to make the project structure more clear, more obvious, more direct, and better describe the business.
A lot of patterns and principles exist in that area, one of them is building the project based on Clean Architecture that focuses on having entities that describe the business capabilities and rules, it’s commonly used along with DDD to build a solid architecture that identifies the business and puts the business rules in a more clear way that lets anyone joins the project to be able to understand what that project actually does.

Vertical slice architecture is another way for structuring the code to be aligned with Agile, so it allows you to build the project around the stories/use cases. For example, if you have an account microservice and there are some use cases as the following:

• register
• login so instead of putting the structure as layered architecture like controllers, services, and repositories/data access objects, you can divide the structure into use cases and inside each use case, you can encapsulate all the needed things to get that use case done. This allows anyone to navigate the code and understands the project by use cases also it will be easier to update the code because in each feature you have all the functions/classes/methods encapsulated there and there is a guarantee that the change you are doing will not affect other places because each use case is encapsulated. It leverages the single responsibility principle because now each use case actually is doing one and only one thing. Also, it reduces the dependency hell problem because now you will not have services depend on other services which leads to circular dependency problems that exist in traditional 3-tier architecture. Vertical slice architecture is commonly used with DDD to encapsulate business rules and constraints and surround them with business use cases/stories.