What’s in a Name: Transparency

Gernot Starke

What’s in a Name: Transparency

Photo from Flickr
Photo from Flickr

Another post to clarify a misused term, this time I’ll cover transparency.

Some developers use transparency to denote abstractions, in the sense of “things are not visible any longer”. For example, people tell me, “this fancy framework (like CORBA) makes network issues transparent and abstracts them away for me”. See the following sketch:

Framework hiding Network from Developer
Framework hiding Network from Developer

The framework hides network details from the developer, so it makes certain details of networking invisible. People call this “transparent”, although it means the opposite!


Transparency (from latin trans: through and parere: follow) means “light can pass through”. In former times, a “transparency” was a usually rectangular piece of translucent plastic which people used for overhead projection (in case you don’t know that word, you’re propably still young…)

Transparency is often used to denote openness, free sharing and distribution of knowledge or information. There’s even a multinational non-governmental organization called Transparency International, which associates transparency with the absence of corruption.

Good Uses of Transparency

In many cases, transparency in this sense of openness is a positive or indispensable quality of arbitrary systems.

  • Market transparency: In economics, market transparency means that “much is known by many”, for example, about what products or services are available at what price and where. This is one foundation of free markets.

  • Organizational or governmental transparency requires laws and policies that allow people to access information held by authorities.

  • Process or project transparency allows stakeholders to access current information about the state of the process or project. In modern development processes like Scrum or Kanban, this transparency is embedded into the process, e.g. in the form of a Kanban board.

In my opinion, a certain amount of transparency is absolutely required within governments and other organizations to prevent malicious behavior. On the other hand, every organization needs to have an appropriate amount of privacy (oh oh, one of these nasty and difficult tradeoffs again…)

Too Much Transparency Can Hurt

Let’s come back to software: When discussing architectures, it can be really helpful to rely on abstractions, to hide certain details.

As an example, the context view of systems provides a great overview of external interfaces, without revealing any internal details of the system under discussion. See the diagram below for in informal example.

Context View of a System
Context View of a System

When discussing architectural structures, you often want to hide details, refrain from divulging the inner workings of some parts of your system. You practice information hiding, using blackboxes to reduce detail and (hopefully) improve overview and understanding.

Too much transparency can really hurt in such cases - potentially overloading people with information they currently don’t need or want.

Let’s try to add (too much) transparency to the context diagram from above:

Overly Transparent Context View of a System
Overly Transparent Context View of a System

When I encounter such diagrams in architecture discussions or documentation, I try to reduce transparency by creating abstractions. I look for elements that can be cohesively grouped together into a blackbox - adding opaqueness.


Opaqueness is the opposite of transparency: Opaque things do not let people peek inside, they do not let light pass through. They’re closed, not open.

It’s really bad to have (too much) opaqueness in governments or organizations, but it’s often good to have appropriate opaqueness in systems - as people usually need to focus on certain details instead of the ultimately_complete_ set of details.

To come back to the network example from the beginning: Frameworks abstracting away the network usually fail (Joel Spolsky explained that in his classical Leaky Abstractions blogpost).

Whitebox versus Blackbox

White- and blackboxes help you apply structural transparency.

As software developer or -architect you should use black- and whiteboxes in your discussion and documentation of systems. Both will be useful for you:

  • Elaborate on important, risky or interesting things, and make those transparent: Explain them, show whiteboxes of their structure and behavior.

  • Abstract away unneccessary details using blackboxes as much as possible. That means you should selectively apply opaqueness and therefore remove transparency.

Structural transparency is one form of architectural transparency, which also covers conceptual transparency.

For example, if you discuss your rather complicated domain model in a joint workshop with developers and business people, you likely want to keep technical details (aka concepts) of your persistence mechanism (e.g. your database query optimizer configuration, storage array RAID level, ext3 vs ext2 file system…) opaque (hidden) from this discussion.

On the other hand, if you discuss performance optimization tactics within your development team, you will make exactly these kinds of details transparent (visible), but will likely hide some of your structural details.

You should therefore explicitly decide when to apply transparency (whitebox) and when to use opaqueness (blackbox). The information needs of your stakeholders provide a simple yet elegant heuristic for this decision: If somebody needs certain information, then you should use transparency. In case this information will not provide additional value, keep it opaque.

Listen to What People Mean…

Sometimes people mean different things than they say. Please be sympathetic - and try to find out what they mean (and ignore part of what they say, as my colleague Phillip Ghadir advises).

Most developers I know and work with really value transparent architectures, projects and organizations. When they say, “framework X makes Y completely transparent”, they often mean that framework X has a nice abstraction for feature Y, hides this feature in a (non-transparent, opaque) blackbox.

In this sense, the Java Persistence API (JPA) makes most of your persistence details opaque, although (very knowledgeable) people from Apache OpenJPA tell you the opposite:

“JPA makes persistence transparent to you, the developer” (quoted from their website)

Thank you…

Thanx for reading – and may you work with transparent architecture and development processes, but may your blackboxes remain opaque!


Thanx to Tammo van Lessen (who came up with the idea to this post - and made opaqueness transparent for me…), Andreas Krüger, Claudia Rauch for their friendly reviews and Piratenmensch for allowing free use of his “Transparent” photo.

Thumb gernot starke

As an innoQ fellow, Gernot participates in the strategic development of the company’s consulting and implementation products. He supports clients as a consultant for software architecture in general and documentation in particular.

More content


Please accept our cookie agreement to see full comments functionality. Read more