Guide to generic and clean naming 🕵️‍♂️

Adam — Mon, 13 Mar 2023 23:01:00 +0000

Developing code is comparable to creating a document or book, which will subsequently be reviewed and utilized by project teams or colleagues. As a developer, it is important to prioritize creating code that is both straightforward to comprehend and straightforward to adjust for future scalability. In essence, it should be both generic and clean.

One of the main principles of good code is maintainability, which means that the code should be easy to modify and maintain over time. This is particularly important for large-scale projects, where many people may be working on the same codebase. By writing clean and well-structured code, you can help ensure that the code remains maintainable over time.

Names are principal for the code base as it makes it easier to maintain and reuse long term, thanks to that it also makes planning future features easier.

When writing code think in terms of long term architecture, modularity and code scalability, how the project is going to grow?

Generic naming 📇

To provide few examples in terms of naming:

import { User } from './model/users';

// Instance of an object
// Desired
const user = new User();

// Not ideal
const sam = new User();

Why Sam above is not ideal? Ideally the code should be generic rather then tying it to personas or personal preferences - it'll also make it easier to edit in the future, when Sam is forgotten.

Think of APIs 🗄️

When designing a class, it's crucial to consider how other developers will be using it. This may involve examining the code base of libraries that you are implementing, such as when working on a REST API or GraphQL. Ideally, you should try to use the same naming conventions as the original API and include appropriate methods and mutations.

enum AssociationType {
  Company = 'COMPANY',
  Project = 'PROJECT'
}

class User {
   get name() {}

   associate(company: Company, associationType: AssociationType) {}

   publish() {}

   retrieve() {}
}

Similarly, when using an external library, it's a good idea to base your naming conventions on those used in the library's API in object oriented way - if any is used.

Consider using synonyms for example - find - get, fetch, retrieve - ideally use the most common names that are used across popular libraries.

update(key: NotificationKey, input: UpdateNotificationInput) {
  return this.model.update(key, input);
}

delete(key: NotificationKey) {
  return this.model.delete(key);
}

findOne(key: NotificationKey) {
  return this.model.get(key);
}

Name entities in human way 🧍‍♂️🧍‍♀️

Instead of using shortcuts, acronyms or slang use human friendly names.

For actions instead of generic evaluate think on what's it's doing underneath, it'll help you structure code base as well, what this function is doing deep down?

When naming variables, it's helpful to use natural language and to think about the actions or functions that the variable performs. Using verbs and associating them with appropriate nouns can make the purpose of the variable clearer. Additionally, passing parameters when naming a variable can provide further explanation and context.

// Update model.
associateWith(company);

// OR
associate(company, "COMPANY");
associate(district, "COMPANY");

// Be careful though with naming and futureproofing such as
associate(a, "COMPANY");

// Submit to external services.
// Having in such way
// it will also make it easier to refactor in future.
publishToCognito(data);

// OR
publish(data, 'COGNITO')
publish(data, 'AD')

import { User } from './model/users';
import { Company } from './model/company';

const users = [new User(), new User()];

const testCompany = new Company();

// Instead of a
// const objects = [new User(), new User()];

for (const user of users) {
  user.associateWith(company);

  user.publish();
}

Long variable naming 🚩

When working on an application, it's common to work with objects that hold data in memory for the application. These objects can have long names depending on their usage, and it's important to consider how the object may evolve over time, and whether it may become a different entity in the future.

Usually when variable names gets too long it means that the logic might need to be separated onto more objects.

// Not ideal
const usersProcessedByExternalServiceReadyToPublish = users.map(user => user.process('SERVICE_NAME'));

// Make use of context of the variable such as
const externalServiceUsers = (users: User[]) => {
  return users.map(user => user.process('SERVICE_NAME'));
}

externalServiceUsers(users);

By following these principles, you can create code that is not only easy to understand and modify, but also efficient, reliable, and scalable. This can help ensure the success of your project in the long run, and make your work as a developer more efficient and rewarding.

Forem: Adam

Guide to generic and clean naming 🕵️‍♂️

Generic naming 📇

Think of APIs 🗄️

Name entities in human way 🧍‍♂️🧍‍♀️

Long variable naming 🚩