Vanta Logo
SPONSOR
Automate SOC 2 & ISO 27001 compliance with Vanta. Get $1,000 off.
Published
4 min read
Up to date

Trevor I. Lasn

Staff Software Engineer, Engineering Manager

Explicit is better than implicit

Clarity is key: being explicit makes your code more readable and maintainable.

I’m convinced that implicitness leads to a higher WTF per Minute (WTFPM) in the long run.

WTF per Minute

Implicitness requires the coder to remember hidden details instead of having them clearly defined in the code. For example, can you tell me why we’re adding “10” here?

JavaScript
// Implicit (bad)
function calculateSalary(a, b) {
return a + b + 10; // a?? b?? WTF is 10?
}

Exactly, that was the point. No one can tell what “10” represents except the person who wrote it, and that’s awful in my opinion. If you have a team of engineers working on a project, how can anyone possibly navigate the codebase with such ambiguity?

Instead of implicitly adding “10”, we can prevent future headaches by simply creating a clear variable for the bonus. In my view, relying too heavily on implicit behavior can cause confusion and make managing the codebase more difficult.

JavaScript
// Explicit (good)
function calculateSalary(cash, equity) {
const bonus = 10; // Explicit bonus variable
return cash + equity + bonus;
}

Tim Peters’ second point in The Zen of Python states, “Explicit is better than implicit,” and I couldn’t agree more.

Imagine a function that grants access to different parts of a system based on a user’s role. In this example, implicit behavior leads to confusion about which roles have which permissions, making the code difficult to maintain.

JavaScript
// Implicit (bad)
function grantAccess(user) {
if (user.role === 'admin') {
return ['read', 'write', 'delete']; // Full access
}
if (user.role === 'editor') {
return ['read', 'write']; // Editors can't delete
}
if (user.role === 'viewer') {
return ['read']; // View-only access
}
// Implicit fallback
return ['none']; // WTF is 'none'?
}
function showAccessControls(user) {
const permissions = grantAccess(user);
if (permissions.includes('read')) {
console.log("User has read access.");
}
if (permissions.includes('write')) {
console.log("User has write access.");
}
if (permissions.includes('delete')) {
console.log("User has delete access.");
}
}
// Example usage
const user1 = { name: "Alice", role: "admin" };
const user2 = { name: "Bob", role: "viewer" };
const user3 = { name: "Charlie", role: "guest" }; // Implicit 'none' fallback
showAccessControls(user1); // Has all access
showAccessControls(user2); // Read-only access
showAccessControls(user3); // No access, but why?

The access control is handled with hard-coded roles and magic strings like ‘none’, making it unclear and unmanageable as more roles are added. Permissions are scattered throughout the code, leading to confusion and maintenance issues for future developers.

JavaScript
// Explicit (good)
const ROLE_PERMISSIONS = {
admin: ['read', 'write', 'delete'],
editor: ['read', 'write'],
viewer: ['read'],
guest: [] // Explicitly defining guest permissions
};
function grantAccess(user) {
const permissions = ROLE_PERMISSIONS[user.role] || ROLE_PERMISSIONS['guest'];
return permissions;
}
function showAccessControls(user) {
const permissions = grantAccess(user);
if (permissions.includes('read')) {
console.log(`${user.name} has read access.`);
}
if (permissions.includes('write')) {
console.log(`${user.name} has write access.`);
}
if (permissions.includes('delete')) {
console.log(`${user.name} has delete access.`);
}
if (permissions.length === 0) {
console.log(`${user.name} has no access.`);
}
}
// Example usage
const user1 = { name: 'Alice', role: 'admin' };
const user2 = { name: 'Bob', role: 'viewer' };
const user3 = { name: 'Charlie', role: 'guest' };
showAccessControls(user1); // Alice has read, write, and delete access.
showAccessControls(user2); // Bob has read access.
showAccessControls(user3); // Charlie has no access.

Why Explicit is Better

  • Explicit Mapping: The ROLE_PERMISSIONS object clearly defines each role and its corresponding permissions.

  • Clarity: By making permissions explicit, there’s no need for magic strings or conditionals scattered across the codebase.

  • Maintainability: Future roles or changes to permissions can be easily updated in one place.

In my opinion, “Explicit is better than implicit” is about choosing clear, direct code over concise but potentially ambiguous alternatives. This principle puts readability and maintainability first, even if it means writing slightly more verbose code.

By being explicit, the intentions behind the code are obvious, making it easier for any developer to understand and work with the codebase.

If you found this article helpful, you might enjoy my free newsletter. I share developer tips and insights to help you grow your skills and career.


More Articles You Might Enjoy

If you enjoyed this article, you might find these related pieces interesting as well. If you like what I have to say, please check out the sponsors who are supporting me. Much appreciated!

Webdev
4 min read

Speed Up Your Website With rel='preconnect' and increase PageSpeed Insights Score

Using link rel='preconnect' can improve your website's performance by reducing connection setup times to key external domains.

Sep 13, 2024
Read article
Webdev
13 min read

10 Essential Terminal Commands Every Developer Should Know

List of useful Unix terminal commands to boost your productivity. Here are some of my favorites.

Aug 21, 2024
Read article
Webdev
3 min read

Preloading Responsive Images

How to properly preload responsive images to improve initial page load

Nov 28, 2024
Read article
Webdev
4 min read

Programming Trends to Watch in 2020 and Beyond

Here are my bets on the programming trends

Jul 19, 2019
Read article
Webdev
4 min read

The What, Why, and How of Using a Skeleton Loading Screen

Skeleton loading screens enhance user experience and make your app feel faster

Nov 12, 2020
Read article
Webdev
3 min read

The HTML Native Search Element

The search HTML element is a container that represents the parts of the web page with search functionality

Dec 2, 2024
Read article
Webdev
3 min read

CSS @supports: Write Future-Proof CSS

Detect CSS feature support and provide smart fallbacks with @supports

Dec 6, 2024
Read article
Webdev
3 min read

CSS content-visibility: The Web Performance Boost You Might Be Missing

The content-visibility CSS property delays rendering an element, including layout and painting, until it is needed

Dec 5, 2024
Read article
Webdev
3 min read

Improve PageSpeed Insights Score with Lazy Loading Iframes

How to save bandwidth and speed up your site by lazy-loading iframes

Sep 13, 2024
Read article

Become a better engineer

Here are engineering resources I've personally vetted and use. They focus on skills you'll actually need to build and scale real projects - the kind of experience that gets you hired or promoted.

Many companies have a fixed annual stipend per engineer (e.g. $2,000) for use towards learning resources. If your company offers this stipend, you can forward them your invoices directly for reimbursement. By using my affiliate links, you support my work and get a discount at the same!


This article was originally published on https://www.trevorlasn.com/blog/explicit-is-better-than-implicit. It was written by a human and polished using grammar tools for clarity.