5 Language Tips to Get Rid of Ambiguity in your Requirements

In this post, I’m going to show you how to create clearer requirements, avoiding common language habits that can introduce ambiguity.


Ambiguous and incomplete requirements can lead to project delays, rework and budget overruns.

We have ambiguous requirements when:

  • A single reader can interpret a requirement in more than one way and is unsure which the intended interpretation is
  • Several readers can interpret a requirement differently from one another

So often, requirements are ambiguous to their readers, despite the writer’s best efforts.

Incorporating the following simple language habits into requirements writing will help eliminate ambiguity and ensure consistency.


Tip 1: Use Active Voice

Passive voice is usually weaker writing since it makes it unclear who or what is doing the action.

Do not assume your reader knows who the actor is. Specifying an actor results in greater sentence clarity.

For example, use the active sentence

The system will generate the report.”

instead of the passive sentence

The report will be generated.”


Tip 2: Avoid Dangling Participles

A participle phrase is a phrase that acts as an adjective. Sometimes, the noun that the participle phrase is intended to modify is not stated in the sentence. In this case, we talk about dangling participle, and it is something to avoid for the sake of clarity.

For example, consider the following sentence:

“After attempting to generate for more than two minutes, the customer will have the option to cancel the report.”

Here the missing word is the system because the system is attempting to generate the report.

This requirement is ambiguous because it sounds as though the customer is attempting to generate the report for two minutes when the writer’s intent is to focus on the length of time it takes the report to generate.

Correcting the dangling participle makes the requirement clearer:

“After attempting to generate for more than two minutes, the system will offer the customer the option to cancel the report.”


Tip 3: Use Specific Nouns

Use specific nouns to clarify who is performing an action.

For example:

The user will be able to export a report once a month.”

The noun user is too generic, maybe we are talking about a customer or vendor.

The following version of the same requirement is much better:

The vendor will be able to export a report once a month.”


Tip 4: Clarify Pronouns

Repeatedly using specific nouns like “system” or “vendor” instead of pronouns may seem a little bit cumbersome, but will improve clarity.

For example, the following requirement is ambiguous because it is not clear which noun the pronoun it is referring to:

“The system will generate the report, and the UI will display the results. It must be redesigned to accommodate the report.”

What must be redesign, the system or the UI?

The next example is clearer because we simply repeat the noun again for the sake of clarity:

“The system will generate the report, and the UI will display the results. The UI must be redesigned to accommodate the report.”


Tip 5: Avoid Would and Should

Using the words would or should literally means that something is optional, but generally, that is not what the writer means when talking about requirements.

So, to avoid confusion, the best option is to use stronger words like “will” and “must”.

For example, consider using the following sentence

“The system will import all data.”

instead of

“The system should import all data.”



Integrating these language habits in your requirements to decrease ambiguity, will give you several benefits, saving you time in your work. Team members will ask for fewer requirements clarifications and the project cycle will be faster!





3 Core Principles to Write Clean Code

In this post I’m going to show you how to write code that is easy to read, maintain and understand.


Coding is for humans.
Clean code is the art of writing code that humans can understand.

Any fool can write code that a computer can understand.
Good programmers write code that humans can understand

Martin Fowler

We’ll walk through 3 core clean coding practices:

  1. Stay Native
  2. Maximize Signal to Noise Ratio
  3. Write Self-Documenting Code

1. Stay Native


Avoid using one language to write another language via strings.
Do not use strings in C#, Java etc. to generate

  • JavaScript
  • HTML
  • XML
  • CSS


2. Maximize Signal to Noise Ratio


Signal is code that follows the TED rule. It is Terse, Expressive and Does one thing.

Noise is anything else:
• Repetition
• Huge Classes
• Long Methods
• High Complexity
• Excessive Indentation
• Unnecessary Comments
• Poor Naming

3. Write Self-Documenting Code


Understanding the original programmer’s intent is the most difficult problem.
Code’s author intent should be clear. Well written code is self-documenting and can reduce and hopefully eliminate the need for comments or external documentation like Javadoc or Wikis.

Self-documenting code does 4 core things:

  1. Expresses author’s intent clearly
  2. Uses layers of abstraction (code navigable through different levels of details)
  3. Is formatted for readability
  4. Favors self-expressing code over comments


Cory House

Robert C. Martin