Note. This is part of my posts covering "Golden Rules of Engineering".
The third rule of engineering is closely related to rule number II, and can be considered an extension of it. This rule says, that you should try to keep the parts and the overall structure of the system you build as transparent as possible.
Transparency in engineering means:
- Your intentions as an author are readily visible. The engineer that comes after you is able to trace your thinking process while you were crafting the part. She is capable of understanding why you did the decisions you did with the overall structure and function.
- The flow of execution can be easily traced. Again, another person is able to see how the system functions and in what order it does it's thing.
Why transparency is necessary
Transparency often translates to simplicity and more "beautiful" design. Depending on the engineer, aesthetically pleasing design might play an important role in how he/she sees the (sub)system as a whole and often effects our perception when considering its suitability for a task.
Transparent design allows other people to more easily find their way through the system and debug why their dependent code isn't working with yours. We have limited capabilities of keeping interactions of several parts in our heads at the same time. You as an engineer ought to help other people to understand your construction. There's a few good heuristics when considering your system's transparency:
- If your fellow engineers complain, that each time they use your system they have to learn it again, it's not transparent enough. Good design translates to obviousness and is easily remembered.
- If you don't yourself remember with minor effort how your system behaves when some time has passed with the creation, it's definitely not transparent enough.
Transparency helps people to build upon your work. Surely you want your system to flourish and evolve over time? Transparent design allows people to take your creation and improve it.
Applications of the this rule in software engineering
So, what transparency means in software development? Some useful guidelines: When execution path is hopping between several OOP classes each hop makes sense and it's purpose is clear. You easily remember why you did the design decisions you did. You are able to relearn the system after you have forgotten the precise details. Your fellow developers are able to debug your code and understand the flow of execution with ease.
Frameworks and libraries often try to ease their usage by constructing complicated execution flows that seem to work magically and "just work". This generally makes the execution path more difficult to follow and debug. With OSS it is especially important to create transparent code, so other people can see what you're trying to achieve and are able to improve it if necessary.