preface

Code is written for people to read and occasionally for machines to execute. Naming is an important technical detail in the coding process; A good name will enhance the readability and maintainability of the code, which affects the software quality and r&d efficiency to a certain extent. Naming can also be difficult, with developers often struggling to find the right name; Next through some naming principles and skills and combined with the development of related scenarios to provide some reference.

Principles and Techniques

In general, good names follow the principle of being readable, easy to understand, and worthy of the name. Readable refers to the name can be read through the mouth sound and not mouthful, convenient for the description and communication between peers; The writable name cannot be too long, cannot have special characters, and can be quickly coded without key combination. Easy to understand refers to the use of simple and commonly used vocabulary on the basis of readable and written, such a name will be more universal, convenient for the vast majority of people to understand. Veritable refers to the name on the basis of easy to understand to ensure that the semantics of the expression to be accurate, not ambiguous.

There are some common strategies and techniques that can help developers with naming:

  1. “Min-length && max-information” principle: Use the fewest characters to express the most information.
  2. The semantic integrity of a name takes precedence over its length.
  3. Try to use vocabulary and abbreviations commonly used in the development world.
  4. Use nouns or gerund phrases to describe entities and phrasal verbs to express motives.
  5. Diversity is allowed, as long as it is readable and writable, accessible and worthy of the name.
  6. Abstract names must be associated with content context.
  7. Learn how to name good open source projects and practice to develop your own style.
  8. There is no such thing as perfection. Balance is the way to go.

Related Naming scenarios

In the development process, many places are involved in naming work, the more common scenarios are: project repository naming, Git branch naming, directory and file naming, code naming. The following describes common naming methods in combination with these scenarios.

Engineering warehouse naming

Project directory names are usually named according to their business characteristics, partly to reflect the work to be done, usually using short, lower-case English words or abbreviations. Sometimes to ensure semantics, names are longer, and it is customary to use a hyphen – to link related words. Examples are as follows:

Moutai Project Name: Moutai Pre-sale project name: Moutai-Presale Moutai activity project name: Moutai-Activity

Git Branch Name

In daily development work, there are basically three scenarios involving new branches: function iteration, online release and problem repair. At the same time, there are also three common English names: feature, release and hotfix, which are corresponding to them and serve as the prefix of branch names. Branch names are usually named with a prefix + description + date structure. The prefix part is fixed, the date part is optional, and the description part uses short English words or phrases to indicate what to do. Description section if too long through the hump or hyphenated – join. There are two common naming methods in the industry. The main difference is the division scheme of branch name. Examples are as follows:

Feature-removelog, release-20210828, hotfix-issue2021 Feature/moutai-Presale /removeLog, release/ Moutai-activity /20210828, hotfix/ Presale /issue2021

Both schemes have their merits; Scheme 1 is simple and suitable for a single Git repository and a single project. Scheme 2 is more descriptive and suitable for multiple projects in a single Git repository. It also has the connotation of group management. In the work, flexible use of these two programs according to the actual situation.

Directory and file naming

Directory and file naming generally follows two logic: realistic and freehand; Realism is a way of naming things from the inside out, based on what the specific content is going to do; Xieyi is a naming method from the outside to the inside of macro management thinking. Directory used to manage files, commonly used freehand naming method; Files are used to manage content, mostly using realistic naming methods, sometimes according to the purpose of the file using freehand naming methods.

Xieyi names are by convention mostly named with lowercase English nouns or noun phrases, which are hyphenated. Examples are as follows:

/ SRC /components/notice-bar/ /vue/ SRC /core/global-api/ /package-lock.json, /tsconfig.json

Realistic names are named according to the content of the file; The names of JavaScript files, for example, are often associated with specific code content, using a camel’s back naming convention. Examples are as follows:

// now.js
export default Date.now || function () {
    return new Date().getTime()
}
// isArray.js
const { toString } = ({});
const arrayTypeString = toString.call([]);
export default Array.isArray || function(value) {
    return toString.call(value) === arrayTypeString;
}

// Queue.js
class Queue {
    constructor() { this.store = []; }
    enqueue(elem) { this.store.push(elem); }
    dequeue() { return this.store.shift(); }
    front() { return this.store[0]; }
    back() { return this.store[this.store.length - 1]; }
    toString() { return this.store; }
    isEmpty() { return this.store.length === 0; }}export default Queue;
Copy the code

Naming in code

Front-end code mainly involves CSS and JavaScript two parts. The underlying logic of CSS coding is to establish a mapping between HTML element selectors and their style rendering, without a lot of logic calculation; As a result, selector naming is relatively trivial in CSS encoding compared to style implementation. CSS naming rules will be covered briefly later. There are a lot of calculation process in JavaScript coding, calculation will involve data storage and data interaction, so there will be a lot of variable naming work, the following focuses on JavaScript naming methods and skills.

General rule: In JavaScript, identifiers can contain only letters or numbers or underscores (” _ “) or dollar signs (” $”), and cannot start with a number.

JavaScript naming methods
  1. Constants are named with a combination of uppercase letters and underscores and are expressed using nouns or gerund phrases:const SUCCESS_CODE = 1;
  2. Variables are named in small hump, using nouns or gerund phrases:var statusCode = 1;,let statusCode = 1;
  3. Functions or function expressions are named in small camel form, using phrasal verbs:function sayHi(){},const sayHi = ()=>1
  4. Classes or namespaces are named in large camel form, using nouns or gerund phrases:class Queue{},const Cookie= {};
  5. Regular expressions use small humps + suffixesRETo use a noun or gerund phrase:const dashAlphaRE=/-([a-z])/g;
  6. React function components are named in the big camel case, using nouns or gerund phrases:function Alert(props) { return <div />; }
  7. In the TypeScriptinterfaceAnd type declarations are named in large camel shape, using nouns or gerund phrases.
JavaScript Naming Techniques
  1. Process variables adopt domain high-frequency vocabulary, which can reduce naming cost, such as:res,req,ret,arr,obj,val,key,elemAnd so on.
  2. Clever underlining_To prevent naming conflicts.
  3. Tool support: Baidu Translation, CODELF variable search tool.
CSS Naming rules
  1. The selector name cannot contain digits or underscores_And a hyphen-“, must start with a letter.
  2. Selector names are lowercase and hyphenated by convention-Except in special cases.
  3. Industry naming methodology recommendation: BEM naming methodology.

conclusion

Basically, any development-related naming entanglements are the result of a lack of metrics and personal preferences. Let go of illogical preferences and develop enforceable standards.