Recommended Appsmith Naming Conventions

Naming conventions are crucial in software development for organizing and maintaining code. This is especially true when developing applications using tools like Appsmith. Internally, we use common naming conventions to make building, maintaining, and extending applications easier.

Let's explore the significance of adopting common naming conventions for widgets, JS objects, pages, queries, and API calls in Appsmith apps. By following standardized naming patterns, developers can create better-structured code, make it easier to find elements with autocomplete, and ultimately save time.

Why Naming Conventions Matter

Enhancing Organization and Structure

When building an application, getting lost in a sea of components and functions is easy. Naming conventions provide a way to organize these elements logically. By using clear, consistent names, developers can quickly understand what each part of the app does, even if they are not the code's original authors.

• Widgets: Prefixing widget names with their type (e.g., btn_ for buttons) helps identify them quickly.
• JS Objects: Consistent naming helps differentiate between functions, variables, and objects.
• Pages: Naming pages logically (e.g., LoginPage, DashboardPage) makes navigation simpler.
• Queries and API Calls: Descriptive names (e.g., getUserData, updateUserDetails) clarify their purpose.

Improving Code Readability

Good naming conventions make code more readable. When names are clear and descriptive, it’s easier for developers to understand the purpose of a function or a variable at a glance. This reduces the cognitive load and makes debugging and enhancing the application easier.

The Benefits of Standardization

Facilitating Team Collaboration

In a team environment, having a standardized naming convention ensures everyone is on the same page. When each team member follows the same guidelines, reading, understanding, and working on each other's code becomes easier. This uniformity reduces the learning curve for new team members and speeds up development.

• Consistency: Standardization eliminates guesswork about how things should be named.
• Clarity: Clear conventions prevent confusion and miscommunication within the team.
• Efficiency: Teams can work more efficiently when everyone knows where to find and how to name elements.

Enabling Efficient Autocomplete

As the number of items in an application grows, finding specific elements can become challenging. A good naming convention leverages the power of autocomplete, making it easier to locate the required components quickly. For instance, typing btn_ in the search bar will list all button widgets, helping developers find what they need without sifting through unrelated items.

Suggested Naming Conventions for Appsmith Apps

Based on our internal conventions, here are some suggestions for your team so you can standardize your own conventions. There is a full table at the bottom.

Widgets

Prefix widget names with their type to make them easily identifiable. This is incredibly helpful when using autocomplete. 

Here are some examples:

• Button: btn_submit, btn_cancel
• Input: inp_username, inp_password
• Table: tbl_userList, tbl_orderHistory

JS Objects

Use descriptive names that reflect their function or the data they handle. While this can be more descriptive, I find it helpful to keep the JS objects named based on their type (state, controller, util) --OR-- their domain (user, order, account). There will be some differences based on whether you are adopting more of a functional vs OOP style, but overall, you should keep it simple.

Since you usually call a method from the object, you want to be sure that it makes sense in the code context. So, for example, a method like user.fetchData() is much better than something like JSObject1.fetchUserData(). While the code may be the same and will work fine either way, the first example is easy to understand without looking at the code, while the second is not.

• Objects: user, order
• Functions: fetchData, calculateTotal
• Variables: list, orderTotal

Pages

Name pages based on their content or purpose. Ideally, these should be fairly short so that the name is not truncated on the menu display in smaller screens. Typically, you want to think of these names as the menu itself, so one word is best.

• Login Page: Login
• Dashboard: Dashboard
• User Profile: Profile

Queries and API Calls

Give queries and API calls names that describe their action and target. This will usually depend on if it is an API or Database connection. To keep the resources neatly organized (especially for code completion), start with the resource or table name FIRST, and then the action that goes with it. This may seem a bit odd from other conventions, but it will make things easier as you go along.

• API: userGet, orderPost
• Query: userProfileSelect, orderDataUpdate

Creating an Appsmith Standards Guide

Establishing Guidelines

Create a comprehensive standards guide to ensure everyone on your team adheres to the same naming conventions. This document should outline the conventions for all elements in your Appsmith app. Here’s how to get started:

1. Define Naming Rules: Clearly state the rules for naming widgets, JS objects, pages, queries, and API calls.
2. Provide Examples: Include plenty of examples to illustrate each rule.
3. Update Regularly: Keep the guide updated as your team’s needs and the application evolve.

Enforcing the Standards

Having a guide is only the first step. You also need to enforce the standards consistently:

• Code Reviews: Incorporate naming convention checks into your code review process.
• Automated Tools: Use linters or other automated tools to flag naming convention violations in your Git repo.
• Training: Educate new team members about the naming conventions and their importance.

Widgets

Widgets have 3 or 4-letter prefixes with an underline to make it visible. This helps organize, view, and FIND widgets more easily, especially with autocomplete. Note that unlike in other areas, we use an underline to separate the prefix for the type from the name of the field. While optional, this does make it much easier to see and read the name

Conclusion

Adopting a common naming convention is vital for maintaining organized, readable, and efficient code in Appsmith apps. By standardizing how you name widgets, JS objects, pages, queries, and API calls, you make it easier for your team to collaborate and for everyone to find elements quickly using autocomplete. Creating and enforcing a standards guide ensures consistency and reliability in your development process, ultimately leading to better and more maintainable applications.

Remember, a well-organized app is easier to work on and more enjoyable to use and develop. Start implementing these naming conventions today and experience the benefits of a more structured and efficient workflow.