Professional Documents
Culture Documents
● Use lower letters when naming database objects. For separating words in the
database object name, use underscore
● Use singular for table names (user, role), and not plural (users, roles). The plural
could lead to some weird table names later (instead of user_has_role, you would
have users_have_roles, etc.)
● If you’re naming entities that represent real-world facts, you should use nouns.
These are tables like employee, customer, city, and country. If possible, use a
single word that exactly describes what is in the table. On the example of our 4
tables, it’s more than clear what data can be found in these tables.
● Imagine that we have tables user and role. We want to add a many-to-many
relation telling us that a user had a certain role. We could use names
user_has_role, or if we want to be shorter – user_role.
How to name columns?
● A primary key column. You should usually have only 1 column serving as a primary
key. It would be the best to simply name this column “id”. You should also name your
PK constraint in a meaningful way. E.g., in our database, the PK of the call table is
named call_pk
● Foreign key columns. Since they store values from the range of primary key of the referenced
table, you should use that table name and “id”, e.g. customer_id or id_customer, employee_id or
employee_id. This will tell us that this is a foreign key column and also point to the referenced table.
In our database, we go with the first option – e.g., customer_id
● Data columns. These are attributes that store real-world data. The same rules could be applied as
the ones used when naming tables. You should use the least possible words to describe what is
stored in that column, e.g., country_name, country_code, customer_name. If you expect that 2 tables
will have the column with the same name, you could add something to keep the name unique. In our
model in the customer table, I’ve used the customer_name as a column name. I’ve also done the
same in the table city with the column city_name. Generally, you can expect that using the word
name alone won’t be enough to keep that column name unique
Naming Conventions for Foreign Keys, Functions, and
Views
● Foreign keys. You should name them in such a manner that they uniquely and clearly
describe what they are – which tables they relate. In our database, the foreign key that
relates tables call and call_outcome is called call_call_outcome.
● Functions. Functions usually perform simple calculations and return values. Therefore,
the best way to name them would be to describe what the function does.
● Views. Most of the rules that are applied to naming stored procedures should be
applied to views.
UML NOTATIONS
UML is popular for its diagrammatic notations. We all know that UML is for visualizing, specifying,
constructing and documenting the components of software and non-software systems. Hence, visualization
is the most important part which needs to be understood and remembered.
UML notations are the most important elements in modeling. Efficient and appropriate use of notations is
very important for making a complete and meaningful model. The model is useless, unless its purpose is
depicted properly.
https://www.tutorialspoint.com/uml/uml_basic_notations.htm
Structural Things
Graphical notations used in structural things are most widely used in UML. These
are considered as the nouns of UML models. Following are the list of structural
things.
● Classes
● Object
● Interface
● Collaboration
● Use case
● Active classes
● Components
● Nodes
Class Notation
Interface Notation
Interface is represented by a circle as shown in the following figure. It has a name which is generally written below
the circle.
Use Case Notation
Use case is represented as an eclipse with a name inside it. It may contain additional responsibilities. Use case is used to
capture high level functionalities of a system.
Actor Notation
An actor can be defined as some internal or external entity that interacts with the system.An actor is used in a use
case diagram to describe the internal or external entities.
Initial State Notation
Initial state is defined to show the start of a process. This notation is used in almost all diagrams.
The usage of Initial State Notation is to show the starting point of a process.
Component Notation
A component in UML is shown in the following figure with a name inside. Additional elements can be added
wherever required.
Component is used to represent any part of a system for which UML diagrams are made.
Node Notation
A node in UML is represented by a square box as shown in the following figure with a name. A node
represents the physical component of the system.
Node is used to represent the physical part of a system such as the server, network, etc.
Database documentation is important because it
meets several needs. For example, it:
● Provides a common language between business decision makers and IT personnel – two different breeds,
usually with no common language, but with a shared ability to read a nice flow chart and discuss it.
● Provides a shortcut to finding ‘hot-spots’ – by looking at a global functionality chart, one can easily outline
the most troublesome parts of the system. In this way, educated decisions can be made about hardware and
software requirements, and the outcome can be easily communicated to the financial department.
● Facilitates a ‘no-panic’ rule – by having proper documentation and using it, the chances of making a wrong
decision are diminished because the risk is easier to assess.
● Makes maintenance easier, and reduces risk when extending or upgrading a system.
● Reduces training costs, by acting as a mediator between newcomers and existing staff. For example, when a
consultant or a new hire comes to the company, having up-to-date documentation reduces the time required
from the existing staff to transfer knowledge.
● Improves productivity of both newcomers and seasoned employees, reducing the likelihood of costly
misunderstandings by providing a glossary of commonly used terms, naming conventions, and even
commonly-used strategy patterns.
A documentation template
Here is an example of the contents of a process documentation template:
● Process flow description: A short introduction, what is the flow for each process? How
is it related to the system as a whole?
● Flow classification: What characterizes the process? What makes it similar or
distinguishes it from other processes?
○ data traffic and the load on the database:
<insert performance metrics here>
○ primary users: …
○ etc …
When the template is ready, start filling it out until you have all processes documented.
Conclusion
Documentation is a time-consuming, but rewarding process. It is also unique to each organization and the
way it operates. The quality of documentation depends greatly on resources and time allocated to it and the
priority it is given.
After reading this article I hope you have developed your own ideas on how to develop and use
documentation, as well as a clear vision of how you will benefit from it.