Coding with these 16 naming rules can save you more than half of your comments!

Preface

This article introduces how to design a reasonable name , Include variable names , Function name and so on .

Good code is better than good comments

, By designing a reasonable name, the code can be easier to understand .

The rules 1： Keep the naming form consistent

Use the same name for the same thing in the code , At the same time, we should follow the user's idioms . Many people may forget the previous naming method when writing variable names , Thus comes a new name . such as  

Image

  object , May be in  A  The document is called  

image

, stay  B  The document is also called  

picture

, This can be confusing . The best way is ：

• For product level entity objects ： The suggestion is front and rear 、 All data tables have unified entity object names ;

• For some specific objects or components of their respective languages , It is suggested that the development team unify the naming rules of entity objects .

• Don't create new terms ！ Maybe you can understand , But it doesn't mean others can understand .

• ** Don't use Pinyin , Don't use pinyin abbreviations ！** When translating Chinese into English , Pick words that are easy to understand .

Here are some naming comparisons ：

//  The correct sample
pageCount //  A field representing the number of pages
updatePageCount() //  And  pageCount  Keep the names the same
toSomething() //  And  Iterable  Of  toList()  It's written in the same way
asSomething() //  And  List  Of  toMap()  In the same way
Point //  User idioms
 
//  The wrong sample
renumberPages() //  And  pageCount  The names are not consistent
convertToSomething() //  With the usual  toX() atypism
wrappedAsSomething() //  With the usual  asX()  atypism
Cartesian //  Not a user idiom


Use well-known terms , It can quickly let users know that only the field is involved , This avoids new nouns or unfamiliar words and makes it more difficult to understand the code .

The rules 2： Avoid abbreviations

Unless abbreviations are well-known words , Otherwise don't abbreviate . Even use abbreviations , You should also follow the customary case rules .

//  The correct sample
pageCount
buildRectangles
IOStream
HttpRequest
 
//  The wrong sample
numPages // num  Abbreviations are not appropriate
buildRects // Rects  Abbreviations are hard to match  Rectangles  Corresponding
InputOutputStream //  No easy to understand abbreviations
HypertextTransferProtocolRequest //  No easy to understand abbreviations


The rules 3： Put the most accurate noun to describe things at the end

When there are multiple noun combinations to describe an object , Put the noun closest to the thing at the end , In this way, we can better understand what kind of thing the variable corresponds to .

//  The correct sample
pageCount //  Number of pages （count）
ConversionSink //  For conversion  sink
ChunkedConversionSink //  One chunked  Of  Conversation Sink
CssFontFaceRule // CSS  Font rules in （rule）
 
//  The wrong sample
numPages //  Not at all  pages  Set
CanvasRenderingContext2D //  Not at all  2D  object
RuleFontFaceCss //  Not at all  CSS


The rules 4： Make the code as coherent as a statement

When making code as coherent as a statement , When you read it, you can know the specific meaning of the code  ——  There is no need to write notes at this time ！, Take the following example , Look at the code and you know what you're doing .

//  The correct sample
if (errors.isEmpty) ...

subscription.cancel();

monsters.where((monster) => monster.hasClaws);


The following is a little difficult to understand .

//  It's emptying  error  Or inventory  errors  Is it empty ？
if (errors.empty) ...

//  Reverse what ？ What is the state after reversal ？
subscription.toggle();

//  Whether to filter the included or not ？
monsters.filter((monster) => monster.hasClaws);


But it's not to force a sentence to make up a sentence , Use easy to understand phrases , So that the reader can clearly 、 Quickly understand the meaning of the code . For example, the following example is a little excessive .

//  The wrong sample
if (theCollectionOfErrors.isEmpty) ...

monsters.producesANewSequenceWhereEach((monster) => monster.hasClaws);


The rules 5： Use nouns for non Boolean attributes or variables

Because it's an attribute , If it's not Boolean , It must be an object , Therefore, using nouns can more clearly name the things corresponding to attributes or variables . meanwhile , If something after operation is involved , You should use the perfect tense of adjectives or Verbs （ Indicates completed ） To modify , Instead of using verbs directly + Noun , This will be mistaken for the action of operating an object .

//  The correct sample
list.length
context.lineWidth
quest.rampagingSwampBeast
sortedList
 
//  The wrong sample
list.deleteItems
sortList


The rules 6： For Boolean attributes that represent certain types of operations that can be performed , Give priority to active words

We often use Boolean values to identify what an object can do , For example, whether it can update , Whether it can close . It is recommended to use active words , Such semantics are clearer . The semantics of adjectives after verb conversion is not clear , And some words are not so intuitive .

//  The correct sample
if (widget.canUpdate) ...
if (window.canClose) ...
if (container.hasElements) ...
if (request.shouldResume) ...

//  The wrong sample
if (widget.updatable) ...
if (window.closeable) ...
if (container.withElements) ...
if (request.resumable) ...


The rules 7： For boolean type parameters , Don't use verbs

For Boolean function parameters , Do not use verbs , But adjectives will be easier to read .

//  The correct sample
Isolate.spawn(entryPoint, message, paused: false);
var copy = List.from(elements, growable: true);
var regExp = RegExp(pattern, caseSensitive: false);


The rules 8： For Boolean attributes and variables , Positive names should be used

This is a little abstract , Just look at an example . When you use reverse attribute names , It's easy to understand when assigning Boolean values r Around the . such as  

isNotEmpty = true

, You have to think 1-2 Seconds to understand what it means . But in fact , Using inverse Boolean values , When writing conditional expressions , Once the brain is short circuited , It's easy to lead to  bug  appear

！

//  The correct sample
bool isEmpty;

//  The wrong sample
bool isNotEmpty;


Of course , For some occasions , Applications may often use the inverse value directly to make judgments , At that time, using positive names might be counterproductive , Because you need to reverse it again . Compared with the ubiquitous negation operator  !, It would be better to use negative naming directly . For example, we need to intercept minors who can use a function .

//  The wrong sample
bool isAdult;
if (! isAdult) {
 return 'Not Allowed for Non Adults'.
}

//  The correct sample
bool isNotAdult;
if (isNotAdult) {
 return 'Not Allowed for Non Adults'.
}


The rules 10： Use imperative verbs to name functions or methods that produce other effects

When using imperative verbs to describe functions , We can clearly know that the function of this function is to do one thing , It's kind of like an order . For a specific operation object , You can add the name or description of the operation object .

//  The correct sample
list.add('element');
queue.removeFirst();
controller.forward();
refreshController.loadMore();


The rules 11： For functions whose main purpose is to return a value, nouns or non imperative verbs are preferred

This kind of function usually doesn't do much , The main purpose is to return a value . If there are no parameters , It's usually a  getter  operation . But sometimes you need to pass a parameter , For example, array subscript , Data filtering conditions, etc . Using nouns or adverbs at this time will be more conducive to understanding the code , And if you add a verb, it will feel a little redundant （ It's usually added  get,find  Verbs like ）.

//  The correct sample
var element = list.elementAt(3);
var first = list.firstWhere(test);
var char = string.codeUnitAt(4);


The rules 12： Do not start the method name with  get

In most cases , Should be removed  

get

. for example , Instead of using  

getBreakfastOrder

, You might as well order one by one  

getter

  attribute , The name is  

breakfastOrder

. If you really need a method to get an object , Then you should also avoid using  get, You can refer to the following two suggestions ：

• The caller of the relationship returns the value if , Then it can be removed directly  get, Use nouns as method nouns , for example
  breakfastOrder()
  , Or use rules 11.

• If you call this method, you care what the method does , Then you can use a more precise description of Verbs , for example  create、download、fetch、calculate、request  wait .

The rules 13： If the method is to copy an object into another representation , So use  toX()  form

This is the same as the following rules 14 Maybe it's a little hard to distinguish , In fact, this means that such an operation is to turn the of an object into an object expressed in a new form . Like the ones that we see all the time  

toJson

,

toString

,

toSet

,

toLocal

  form . This approach is mostly irreversible .

The rules 14： If you return a different representation of the original object , So use  asX()  form

asX  In fact, it's like we do object conversion , We have the following code ：

if ((object as String) == 'a') {
 ...
}


asX  The form is similar , The converted object can actually reflect the characteristics of the original object , That is to say, you can come back through certain means . For example, the following situation ：

var map = table.asMap();
var list = bytes.asFloat32List();
var future = subscription.asFuture();


The rules 15： Do not repeat the parameter name on the method name

The parameter name can be read in conjunction with the verb of the method , Adding parameter names is a bit redundant .

//  The correct sample
list.add(element);
map.remove(key);

//  The wrong sample
list.addElement(element)
map.removeKey(key)


This is not absolute , For example, if adding parameters can eliminate the meaning of different functions of the same class , So it can be , Take the following example .

//  The correct sample
map.containsKey(key);
map.containsValue(value);


The rules 16： For generics , Follow the general mnemonic

Usually in generics , We will use the following mnemonics to represent different generic parameters , You need to follow these rules to help understand generics .

• E： Represents the generic parameter of the collection class , for example ：

class IterableBase<E> {}
class List<E> {}
class HashSet<E> {}
class RedBlackTree<E> {}


• K and  V Express  key  and  value  The generic parameter , for example ：

class Map<K, V> {}
class Multimap<K, V> {}
class MapEntry<K, V> {}


• R  A generic parameter that represents a return value , for example ：

abstract class ExpressionVisitor<R> {
 R visitBinary(BinaryExpression node);
 R visitLiteral(LiteralExpression node);
 R visitUnary(UnaryExpression node);
}


• Other situations , Usually use  T、S  and  U  To identify generics , In practice, if it can help to understand , You can also use the word （ title case ） As a generic parameter , Below 3 There are no problems .

class Future<T> {
 Future<S> then<S>(FutureOr<S> onValue(T value)) => ...
}

class Graph<N, E> {
 final List<N> nodes = [];
 final List<E> edges = [];
}

class Graph<Node, Edge> {
 final List<Node> nodes = [];
 final List<Edge> edges = [];
}


summary

We often worry about writing notes , I think it's a waste of time to write notes . actually , If you use the code name , It can save a lot of time writing comments . What we really want to write is more documents , Documents can help us 、 Help the team sort out and develop business processes 、 Logic . therefore , The higher level of coding is to use good coding naming rules and styles to understand functions through code , Write less notes , Then make time to write documents .

Welcome to follow individual public number ：

Ma Nong on the island