DEV Community: Luís Soares

Unit testing a gateway with Javalin

Luís Soares — Fri, 05 Jun 2020 15:01:01 +0000

In Kotlin/Java, how would you test that your app is properly consuming an external REST API?

Anti-patterns of automated software testing

Luís Soares — Sun, 24 May 2020 13:06:35 +0000

Sometimes it’s easier to learn from ‘what not to do’ rather than from ‘what to do’. So I wrote this article about stuff you should avoid in your tests. Hope you enjoy.

You should be using Value Objects

Luís Soares — Wed, 13 May 2020 13:25:05 +0000

Value objects are one of the building blocks of domain-driven design. Let’s see the value they bring.

Continue reading on The Startup »

Anti-patterns of automated software testing

Luís Soares — Thu, 16 Apr 2020 17:08:30 +0000

Sometimes it’s easier to learn from ‘what not to do’ rather than from ‘what to do’. Anti-patter_ns represent c_ommon bad practices, code smells and pitfalls, in this case, when creating automated tests. You should learn them so that you can spot them.

Creating patterns to describe something creates nomenclature. Once you have a name for something, it’s easier to recognize when you see it again.

The Productive Programmer, Neal Ford

📝 The list applies regardless of the language/runtime.

No clear structure within the test

Not following an expectable structure in each test makes it hard to maintain it. Tests are living code documentation , so everyone should be able to quickly read/change them.

Arrange, Act, Assert is a pattern for structuring code in test methods. Basically, you organize your code in phases for the sake of clarity. It can be mapped to Setup, Exercise, Verify, Teardown in the four-phase test pattern and to Given, When, Then in BDD:

Arrange /Given/Setup: initialization of the SUT (system under test, whatever you’re testing) and other dependencies like mocks and fakes;
Act /When/Exercise: the call to the method being tested — ideally a single-liner;
Assert /Then/Verify: assertions of the output or verifications of calls made;
(Optional) Teardown: if there are resources to be freed.

As a consequence, I usually have 3 phases visually separated by empty lines. If you reply with: “But I have lots of code in my test! I need more than 2 empty lines!”, I’d say “that’s likely a design smell”: you might be testing a god object which you need to split, you might need to create a “local DSL” — high-level helper methods, or you could consider extracting the common setup and teardown elsewhere.

TL;DR

👎 Having no consistent test structure, harming readability;

👍 Applying Arrange/Act/Assert consistently, visually separated by newlines.

Refactoring when adding a feature

Adding a new feature bears some risk and stress, even when you do TDD. So, why would you make things worse by fixing this or improving that simultaneously? This can lead to an explosion of untested cases and hard-to-track down bugs, but the worse is the anxiety it brings.

So the bottom line is: relax and focus on the feature at hand. It’s true that you should leave the code in a better state than you found it — opportunistic refactoring), but please do it before (if it helps the feature) or after the feature. If it’s after, consider writing the refactoring ideas in a sheet of paper, as TODOs in the code, in tasks/stories in your tracker, to reduce the “fear of forgetting”.

TL;DR

👎 Improving things you step into, while you create a feature;

👍 Doing the refactor before the feature or noting it down for later.

Changing implementation to make tests possible

I recently read Test-Driven Development by Example by Kent Beck and I was a bit disappointed that he was teaching why and how to test private methods (using Java reflection). Later, I think he made up his mind:

// Detect dark theme var iframe = document.getElementById('tweet-1258954349314625538-313'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1258954349314625538&theme=dark" }

I never faced a situation where I needed to test private methods; it always feels like a big red flag.

In “unit test”, the word unit represents a piece of a public interface. Private methods are an implementation detail — auxiliaries of public methods — and are to be tested indirectly through them! There’s probably no exception to this rule. If you find it hard to test all private method possibilities, then maybe you have a god object that you should split into multiple components.

“Ah.. but I can make the method public!”. That’s even worse… you should not change the code implementation just for making testing possible. Testing private methods is just an example, but there’s much more. This usually means you’re doing something wrong.

TL;DR

👎 Changing the implementation solely for the sake of making testing possible;

👍 Be hinted to redesign the implementation code because the tests are hard to write.

The test is hard to write

A common reason for a hard-to-write-test is that you’re new to the problem and need to get more familiar with it. In that case, try explaining the problem to someone (or even to a duck) or take a break to get your ideas organized.

If you’re using TDD, you can try the starter test (a really basic one) or the explanatory test (the one you’d use to explain to someone).

However, if the test ends up being too complicated, too long (e.g. lots of setup code), or it feels like a hack, probably there’s a better way. A good way of finding if your code is too complicated is the need to add comments to explain it: code should speak for itself.

Generally speaking, tests that are hard to write or understand are a symptom of bad code design. Tests are a client of the implementation code — when tests of a component are hard to write, you can extrapolate how hard is to use that component.

If it’s hard to write a test, it’s a signal that you have a design problem, not a testing problem. Loosely coupled, highly cohesive code is easy to test.

Extreme Programming Explained, Kent Beck

In that case, you should consider if the implementation code needs a refactor to make it easier to test and maintain. The solution may be divide and conquer, as your SUT may be a god object. It may also be wise to try to use more adequate software design patterns.

TL;DR

👎 Making hacks that need an explanation or having complicated setups, so that a scenario can be tested;

👍 Considering a code redesign when a test is hard to write.

Optimizing DRY

This is the most common mistake I encounter. People see a repeated value and they will immediately create a variable for it. That’s not an early optimization: it’s just making documentation (tests) harder to read.

In tests, some repetition is bearable for the sake of clarity. This is one of the few differences between test code and implementation code. Test code ≠ implementation code. Tests should more DAMP (Descriptive And Meaningful Phrases) than DRY (Don’t Repeat Yourself).

On a related note, I hate when I have to scroll up and down or open multiple files to understand a single test. A typical case is a folder full of sample data that is used everywhere. Sometimes it’s fine to leave repeated setup and teardown in all tests in all cases. Tests should be self-evident. Tests are documentation. Therefore, I’d prefer to read tests top-down, like in a user manual (imagine if you had to swap pages multiple times when reading your washing machine manual…). This is also a callout to avoid using globals in tests (i.e., class or file globals).

A very hard to read test; the more dependency arrows, the harder to read

TL;DR

👎 Pursuing DRYness by creating variables and functions in tests;

👍 Starting with everything local and evident; break the rule only if it brings more value.

Very similar test cases

Copy-pasting of more than one line of code should generally raise an alarm in your head. Well… it’s OK to do it just to make it work, but you should fix it later. It’s worse if you copy an entire test where only the initial values vary. This calls out loud to resort to table-driven testing, also known as data-driven testing. Table-driven testing allows running the same test multiple times, one per set of inputs and expected output (or other consequences).

   Input | Output    
   -----------------
       1 | 1         
       2 | 2         
       3 | Fizz      
       5 | Buzz      
      15 | Fizz Buzz

📝 It’s not my goal to teach you here about it, so I’ll leave a few links:

JUnit parameterized tests (Java, Kotlin);
NUnit parameterized tests_ (C#);_
Jest each method (JavaScript, TypeScript);
RSpec shared_examples (Ruby);
Table-driven testing in Go, Python, and PHP.

Bottom line: use table-driven testing if you keep duplicating the same test with different data. As advantages, you’ll have:

Less code because you don’t repeat very similar tests;
Easy comparison of test cases;
Quick ability to add or remove test cases;
Better documentation, because positive, negative, and edge cases are explicit.

⚠️ In table-driven testing, do not mix the happy path with the error scenarios . These should be kept apart for clarity reasons.

Finally, consider the trade-off you’re making, given that the tests become less DAMP when applying this technique.

TL;DR

👎 Copy-pasting many similar chunks of test code to add new test cases;

👍 Learning how to do table-driven testing with your language/library.

Testing everything

According to the law of diminishing returns, there’s a point where the cost to add tests does not compensate for its benefits anymore.

Applied to automated testing, not every possibility needs to be tested. Some situations can be left untested:

some are too rare or exotic;
others will quickly arise when using the software (e.g. missing env. var.)
many won’t have a big impact if they fail (e.g. CSS styling, animations).

How to determine if a certain test is worth it? You should roughly calculate its benefit-cost ratio: is benefit/cost ≥ 1? Within benefit consider the permanent prevention against the problem (testing as a safety net). For the cost, take into account the effort to simulate the test scenario and the resources (lines of code to maintain, time to run) it will require from thereon.

TL;DR

👎 Religiously trying to test everything;

👍 Analyzing the cost-ratio test by test, to decide if it’s worth it.

Other smells and anti-patterns

Using the word “and” when describing a test : this hints that you should split the test in two, each asserting/verifying different things (check code example above);
Testing lots of combinations (combinatorial explosion): this is a smell that you have multiple components into one; the solution is to recognize them and slowly split them apart.
Treating test code as a second class citizen : test code is your safety net so take good care of it; most good code practices are transversal to any source code (e.g. avoid globals);
Not discarding a spike ’s code, especially when doing TDD : a spike is a learning tool; its code should not be kept and evolve;
Testing business rules though UI : business rules should be tested regardless of the UI being used. Of course, end-to-end testing is an exception;
Quantity without diversity : test cases should be different somehow — do not add cases for the sake of quantity; the same applies to test scenarios: they should vary;
Mocking what you don’t own: avoid leakage of libraries into your software (runtime or external); there are alternatives like wrappers and mock servers;
Conditionals in tests : having “ifs” in tests is wrong; it’s proof that you need another test scenario;
Overvaluing test coverage : coverage shouldn’t be something you pursue just for the sake of it because you may be near 100% and still have crappy tests. Anyway, with TDD, coverage is almost an irrelevant concept.
Early optimization : in TDD, always reduce the “distance” between a red (now) and a green state (future). Do the “quick and dirty” implementation even if it means to return a constant or do an ugly or slow implementation. Make it pass, then make it beautiful. The reason is not only psychological — it’s dopamine-freeing to see a green state — but it’s also about learning sooner. You learn, from the start, more about the problem and the solution (e.g. code design) if you make it pass first.

Final remarks

One could notice that a lot of anti-patterns in tests can be attributed to an anti-pattern in implementation: the god object: having huge test files, having long tests, a test being hard to write, among others are warning signs. That said, my advice is:

Write software in a top-down approach , so that you can more easily understand the “components below” deriving from the “ones above” (and you only implement what’s needed);
Recognize when you have multiple reasons to change a component so you can split it (single-responsibility principle).

Bottom line: if it’s complicated, you’re doing it wrong. The ideal solution is usually simple; you just need to be persevering and iterate until you achieve it.

The presented list was not supposed to be exhaustive since there are good resources out there (e.g. StackOverflow’s thread, Yegor Bugayenko’s list). Software Testing Anti-patterns by Kostis Kapelonis is a must-read. You can find good patterns in Part III of Test-Driven Development by Example by Kent Beck. Finally, watch TDD, Where Did It All Go Wrong by Ian Cooper:

Our approach to quality in Volkswagen Software Dev Center Lisbon

Luís Soares — Wed, 18 Sep 2019 11:24:31 +0000

Assuring quality on the demanding software products we build at Volkswagen SDC:LX is not easy. Saying we’re agile is not enough, so I’ll present the soft and hard factors that ensure the required standards are met.

Volkswagen SDC:LX

As a disclaimer, this is solely my point of view.

Culture

Team members are part of the hiring evaluation stages , which greatly improves compatibility and ensures the culture and methodology continuity.
Critical thinking is highly appreciated and everyone is free to challenge what’s defined and the others (regardless of the role). This is supported by our non-judgmental environment.
We rely on a scientific approach to problems by setting hypotheses and assumptions and seeking to confirm or disprove them.
Team empowerment fosters ownership : since the team is responsible for the product (building and operating it), everyone is more dedicated to it. We have a flat structure and teams are balanced (PMs, designers and developers) for autonomy reasons.
Context switching is expensive, so focus is essential to our way of working. For example, you only work in a single product at a time.
Discussions of development good practices are welcomed, valued and common.
We promote rotation amongst teams and even offices (we run programs for the interchange of people between offices). This allows the sharing of ideas and solutions, to compare and learn, and to question the implemented habits.
A feedback culture promotes individual/team improvement (team, product and office retrospectives, individual feedback, etc.). Everyone reflects on it and gets continuously better.
Transparency and happiness are kept so everyone feels part of the office. Weekly office syncs are held with everyone and social events are regularly organized by the happiness team.
A culture of constant learning is held. It’s common to share interesting articles and other web resources. We have a book library and free access to online courses. We organize, attend, and host events. We have internal weekly meetups where anyone can present something.

Practices

Every potential product starts with a scoping meeting to define the boundaries of the problem to be tackled; this is followed by a discovery/framing phase to better understand the problem and validate if we should move on. If so, we do an inception to develop an MVP so we can quickly test it within a real environment. This ensures we do the minimum to validate it quickly and get feedback as soon as possible (lean development).
A user-centric philosophy is followed. Every feature in the backlog is written in a clear way that brings value for the user; this explains you won’t find stories split by backend and frontend — we always split “vertically”.
We do small experiments within the teams and the office, by trying new things that could improve our work (e.g. regarding our practices). Everyone is free to suggest improvements.
Most documents are produced in a collaborative way and are quickly iterated. This is achieved by the use of collaborative tools like digital whiteboards, word processors, issue trackers, etc.
By constantly pairing, we are running continuous live code reviews , as opposed to decoupled/async code reviews; the feedback is immediate and contextualized, thus more valuable.
Pairing guarantees knowledge sharing because of its nature and also due to the daily pair rotations. As a consequence, all the team knows the codebase/architecture and it’s less dependent on individuals (‘no heroes’ culture). Pairing also happens with designers and product managers (PMs) which promotes know-how sharing amongst roles.
Decisions are debated which improves their quality. By default, they are done as a pair but if they feel needed, they’ll reach out the team or even other teams for discussion.
Besides all the automatic quality checks, manual testing is done by the team, per feature: developers validate the stories and PMs/designers accept them in a near-production environment.
Continuous improvement happens in a codebase level. Refactorings are usually done when working on a story. Other refactors and tech debts are tracked so they are not lost (any team member can add them to the backlog). Keeping the code maintainable is a core value.
Voluntary facilitators improve the quality and outcome of meetings. They make sure the meeting is time-boxed and focused. We start by diverging and converge in the end.
Test Driven Development ( TDD ) ensures a better software design and code gets documented and tested as a consequence. Since we focus on the behavior (BDD), the implementation derives directly from the user requirements.
The whole team (and possibly other people) is frequently invited to design sessions (e.g. to design a feature) organized by the designers. This feedback is taken into consideration and the designs are iterated.

Technology

Developers are full-stack which promotes feature know-how/ownership from top to bottom, start to end, and a skill set across multiple technologies.
There’s a general passion for technology (that’s almost a requirement) but we have methods to make sure it doesn’t bias our decisions so we keep our focus on the users.
The team is free to choose the languages, runtimes, and frameworks and tries to make informed decisions when picking them.
For each language and runtime, we choose and set up our IDEs, editors, utilities, and plugins so that we get code warnings, tips, validations, autocomplete, etc. These are kept always up-to-date.
Attention to warnings : every warning in the code editor, logs, or other, is a symptom of something, so we always try to fix them.
Static code analysis : the code is automatically analyzed regarding code conventions and other concerns.
Versions checking : we make sure that the latest versions of the runtimes, frameworks, and libraries are used. This reduces the number of bugs such as security fixes.
Unit testing , integration testing , and end-to-end (E2E) testing are done by default for all software components, testing multiple layers and combinations. Since those are developed in TDD, we feel really safe when refactoring or adding features. All the test suites are run per code push.
Continuous Delivery/Integration (CD/CI): the features are pushed to the master branch (trunk based development) and automatically deployed to pre-production. That way, we don’t have to keep track of lots of feature branches and releases. The CI pipeline is constantly visible on a TV.
Different environments in the CI before reaching production: if any test fails, the code is not deployed. This also gives more opportunities to find problems before production since all team members, directors and POs use them.

More info.

Emotions management when pair programming

Luís Soares — Tue, 06 Nov 2018 15:42:32 +0000

Emotion management when pair programming

Pairing is not just two people working together. Mutual respect, emotion management and other psychological factors come into play. Doing it well takes time, so be patient, repeat it properly until you can reach the “pairing zone”.

If you don’t understand the advantages of pairing, perhaps you should start with that. Let’s quickly recap them:

You’re “forced” to put your thoughts and ideas into concrete words, which contributes to solving problems and helps you consolidating knowledge;
Pairs complement/help each other (e.g. you don’t get stuck for hours in a bug); you move steadily and with increased predictability; you feel useful at the end of the day;
The focus is higher since you have to respect your pair’s time and effort (e.g. you won’t be checking your phone every time) and you’ll have someone helping to manage time (e.g. who can tell you when you’re sliding away);
Code reviews and decisions happen “on-the-fly” rather than in a separate phase (better context, less long discussions); quality is improved as you’re actively reviewing;
You learn on the job much more, as you may be pairing with an expert on the topic;
The knowledge is spread across the team; you share solutions and patterns; there are no preassigned tasks; the team doesn’t depend on specific people to move forward; on-boarding/off-boarding is not a pain.

Let’s now go through some tips for the driver (the one writing the code) and the navigator (the one specifying).

Discipline and focus

Clear out the assumptions before starting. Make sure you read the user story in detail. Don’t rush to start. Agree on the strategy beforehand (using flowcharts, ‘to do’ lists, mental maps, and other diagrams).
Timebox experiments. If one needs to make some code experiment or a small spike, propose a time slot to try it out (e.g. 15 min., 1 hour, till lunch). That will help keep focus.
As the driver dedicates more mental power to interact with the computer, the navigator has more responsibility to keep things on tracks (ensuring focus at the story). It’s easy to detour but you can say: “Is that related to the story? Could we do it later?”. Otherwise, you’ll keep “opening brackets without closing any”.
Try to understand if the driver is refactoring too soon. Refactoring should always happen after getting the tests green. Also, be aware if the refactoring is too big or unrelated to the user story; that means it’s time to create a specific story for that.
Do not keep interrupting the driver with early optimizations/improvement s (e.g. typos, code repetitions). Think of time split into small slots and wait for one to end to expose them. In TDD, you should only do optimizations/improvements when the tests are green. Write them in a notebook so you can mention them when possible (and you can relax meanwhile). Interestingly, many of my notes are scratched as the code evolved meanwhile.
Respect pauses. Realize and enjoy when you accomplished something and propose a pause. Focused and intense moments should be followed by pauses (try the Pomodoro technique if it helps).

Respect and empathy

Ask the driver to think aloud but respect that not everything needs to be put into words. Sometimes, just go along and/or wait for the experiment to finish. Try to follow it but interrupt if you’re lost.
Create empathy with the navigator, and keep probing if your pair is still on board. While listening, wait till the end of the sentence rather guessing it. Look at your pair sometimes when speaking/listening.
Have the initiative to switch roles. You can propose the ‘specifier/implementer’ technique (one writes the spec, the other implements) if you need to explain a complex topic or feel the navigator is lost.
Do not criticize the apparently “non-sense Google searches” made by the driver; that’s part of the research. If you let the driver finish thoughts, there’ll be two perspectives to face the problem.
Avoid condescending explanations. Try to teach within the context and in small chunks rather than shoving/showing off your immense knowledge about the project.
Avoid repeating “I know that” , “Yes I saw that”. Even if true, you might be preventing future teachings. Just move on. Prefer to say “interesting” when you learn something.
Avoid sentences that start with “in my last company” or “given my experience”. Go directly the the underlying facts.
The driver is responsible for the implementing but if you see him/her stuck, you may politely say “Can I try something?” so you can switch roles.
Be aware, from time to time, if the navigator wants to say something. He/she may be holding to avoid interrupting you, so pause sometimes to listen.
Make questions. Every question is valid but not all answers are. Challenge the driver. Phrase questions without looking like a “smart ass”.
Don’t dictate code : if you know what you want, just type it down. Dictating is tiring to understand and can seem condescending.
If you enjoyed the day, finish it saying “thanks for the day” or “it was a nice pairing with you today”.

Emotions

Don’t stress if you don’t understand everything, especially when you’re the new guy. Try to help somehow (code contributions aren’t the only contributions). Your mental models will iterate and refine with time.
Don’t get too personal ; pairs work closely and it can be emotionally hard. For example, it’s easy to feel attacked if someone criticizes your code, but you can learn how to deal with it, on both roles. Coding is just a tool; not a personal trait.
Be open about your weaknesses from the start; mention your strengths later.
Be gentle and tolerant. Don’t make the other feel threatened for not knowing something. Never say “didn’t you know that?”. Don’t judge the other’s knowledge. Pairing is a symbiosis; not a competition.
Behavior generates behavior, so don’t let feelings escalate in the wrong direction. Making fun isn’t welcomed. Strive for empathy and positive mood.
People are different, so adjust to your pair. You want to be treated that way so think “what if I was in his/her shoes” often.
Accept that you’ll be slower sometimes so manage anxiety. You feel you could go so much faster on your own, but recall that you belong to a team that desires no single points of know-how. Be patient. You’re not only building software but also a team that can do it.

In the end, if you’re having a lot of effort you may be doing it wrong; or your pair may be making things hard. If that’s the case, ask for a personal feedback session where you clearly state the areas of improvement.

Building an autonomous UI

Luís Soares — Mon, 14 May 2018 09:18:01 +0000

An autonomous UI doesn’t rely on animations, sound, colors, shortcuts, and help to be understood and used. It doesn’t mean it shouldn’t have them but it shouldn’t depend on them.

Animation

Animations help to reinforce the chosen visual metaphor (e.g. a slide right to express a card removal; a loader to show there’s some background job) and create visual harmony (e.g. to soften transitions). They should be simple, tenuous, used consistently (e.g. fade in vs fade out to express opposite concepts). Use them in moderation and if they bring value. Animations aren’t supposed to be constantly noticed by users, as they’d be distracting from what matters. They shouldn’t be used just to “make the app cooler”.

Excessive and heavy animations can be really bad, consuming lots of CPU time or being harmful to people with certain disabilities (e.g. epilepsy), so in certain cases, it should be possible to turn them off.

A nice experiment to try is to turn off all the animations and confirm if the UI is still usable (preferably with users). This helps to understand if certain animations are there to camouflage or reinforce bad or good design decisions.

Color

Color, shape, position, contrast, texture are basic elements of graphical design. Colors are associated with moods and emotions that may vary with culture; they can also serve to highlight elements, thus having high expressive power. However, you should never use color as the single differentiating element. If you have several items that you need to distinguish, color can reinforce it, but it shouldn’t be used alone. The main reason is accessibility (e.g. people with color blindness would have problems using such UIs). On the other hand, you usually don’t know the color limitations of the users’ displays.

In addition to color, the shape also helps you realize what the icon is (Google Drive)

The general rule is to use shape to differentiate items and color as an addition. Luminosity itself is also a differentiating element. To know if you pass this “color test”, try to use your interface in shades of gray and see if it needs some fix.

Help

A good interface doesn’t require the user to depend on help to perform tasks. This is not saying that the application shouldn’t have a user manual or contextual help. On the contrary, the help must exist and be as contextualized as possible (e.g. well-placed tooltips; contextual links to help); what you should aim for is that the users shouldn’t have to consult it, especially on repeated usage. A good UI should “speak for itself”. For this, a minimalist design, a natural flow of information, a good information architecture, among others contribute a lot.

Avoid instructions; you can do it naturally, transparently and implicitly. If your UI needs and relies on instructions, “you’re doing it wrong”. Well, not necessary, but try to build the UI like that was true.

If users rely too much on help, this may be a symptom that something is wrong with the design or even with the information architecture.

Sound

A sound effect at the right time can be helpful. It can be used to draw attention (e.g. new message arrived), to reinforce a concept (e.g. successful operation), to signal an error, among others.

Like animations, sound must always be used as a complement to the UI and never as a primary form of communication. You should never rely on sound since the user may lack a sound device or have it muted, be in a noisy place or have some kind of hearing disability.

If adding a certain sound really brings value, then it should be used with consideration. Inappropriate use can be annoying and tiring.

Mouse

The dependence of the mouse can also sometimes be negative. Typical examples are mouse-over and right mouse button operations which become unusable on touch-only devices. You can use the right button, but only for the sake of flexibility and speed — and again, an alternative method of interaction. For navigation, consider also keyboard shortcuts.

The same applies to the mouse wheel; there should exist an alternative to its use. Finally, depending solely on the mouse also impacts accessibility.

Keyboard

Keyboard shortcuts (e.g. Ctrl+C to copy, Tab to navigate) aren’t supposed to be the only means of interaction — most are for advanced users. What’s done with a shortcut should be explicitly offered in the UI (hidden under menus or not).

Navigation controls

You shouldn’t expect users to click on the browser ‘refresh’ button to recover from errors or to force data updates. Also, try to avoid depending on the ‘back’ and ‘forward’ buttons to navigate. The software should be self-contained in terms of navigation, error recovery and data update (specially SPAs).

In native Android apps, you can offer an alternative to ‘menu’ and ‘back’ in the app UI itself.

Permissions

In web and native apps, you can ask for hardware and software permissions (e.g. camera, microphone, location, showing notifications) but your app should work without them (e.g. if the user declined permission). If it depends on them to be used, you should explain it to users.

Messages

Don’t assume users read error/warning messages in dialogs. Many times they dismiss them without reading their text. Don’t punish users for missing them. The app should have ways to repeat the message or display it inline (contextually) instead.

Ids

Don’t create UI use cases that depend on ids (database identifiers) to be accomplished. For example, why would you show identifiers on a data table? Why would you let the user assign an object to another requesting its id? Friendly titles are for humans; identifiers are for machines.

Why show ids when creating objects?

Why display ids in data tables?

Conclusion

As a general rule of thumb, try to design each “place in the app” in a way that the users wouldn’t need to know what they’ve done to get there. They could be really forgetful or always going to coffee. That said, each place should have the necessary information to be understood by itself allowing users to resume the task at hands.

When designing UIs, we need to decide what are the means of interaction and divide them into primary and auxiliary. Generally, animation, sounds, color, and help, should be seen as an auxiliary — to reinforce or complement the main concepts and ideas. Of course, sometimes they can be of great value (e.g. inline icons to give contextual help, breadcrumbs as shortcuts), but at least you should try to design the UI without depending on them. The general guideline is to turn all off, and test how the UI “behaves”.

In web apps/sites, it’s obvious at these days that you should avoid depending on the target audience’s display capabilities, like screen size and resolution, color schema, etc. Embrace responsive and adaptive design. Also, beware and run away from non-standard dependencies like Flash, Java, and Silverlight.

Don’t assume users will see initially hidden information like tooltips, unselected tabs, dropdown options, etc. Bear in mind there are certain interaction design patterns that are inherently an alternative to something (auxiliary), and never the primordial form of interaction. For example, breadcrumbs shouldn’t be the only form of navigation; these are only a shortcut/alternative to the main navigation.

There are items that you want users to see and others that they can discover later (depending on task importance). However, you should present items in ways that they wouldn’t need to be instructed beforehand. Design the UI in such a way that it can be self discoverable. Aim for self explainable, autonomous and independent UIs.

Note that the rules above should serve only as a reference, as they may have exceptions (however, to break the rules, you need to know them). Only by testing with users can you be sure that they are met. It’s never enough to repeat that just 5 users are enough to detect most UI problems.

Original article in Portuguese.