How to name code

Source: www.cyningsun.com/07-04-2020/…

There are only two hard things in Computer Science: cache invalidation and naming things. —— Phil Karlton

preface

Developers tend to talk a lot about design, architecture, and microservices, but pay little attention to how the design and architecture fit into the code itself. While architecture and design are important, code is not. As Robert C.Martin says, “The code is the design.” When you look at good code, you can see the beautiful design behind it.

Good code, the first step is to give each class, function, and variable a good name. Unfortunately, most people have no idea how to come up with a good name. After all, naming is not technically the domain of computer science. A good name for a word can be simple, image, intuitive show its function or even principle, such as:

• SYN flood: Indicates a FLOOd-like SYN request

• Pipeline: Transmits data like a Pipeline, in sequence and in one direction

That’s just the problem solving domain. It’s not the hardest part. The hardest part, in actual development, is facing the problem analysis domain. If your thinking structure, level is not clear, abstraction of a variety of states are not orthogonal, overlapping each other, cross, and then think of a better name, then there is no way back; If you don’t know what A dish is supposed to be called, you can’t possibly know what it is (A Rose by Any Other Name Will End Up As A Cabbage), so the naming process is also about tidying Up ideas.

According to the past experience, the name can be divided into three levels. The first two levels cover the dilemma of Solution Space, and the last Level covers the dilemma of Problem Space

• Level 1: Bad smell. It takes a bad smell to realize you need to change
• Level 2: Naming techniques, some simple naming techniques, understand where you can improve
• Level 3: Domain language, the tao of naming, naming is a systematic transition from business to development.

Level 1: Bad taste

• Meaningless naming

  I.e. data, info, record

• Abstract naming

  I.e. data, Object, Helper, tool, Manager, Processor, handler, maker, util, conf, thing, info, amount, details, do, execute, perform, operate, manage, handle

  Not precise enough. No doubt you did name data and objects, but you would have known that even without the vague names. Rename data to a more descriptive name to identify the data

• Referred to as”

  i.e. mod

  Mod is like a short name for a word, and you may not be sure whether it’s mode or module

• vague

  i.e. Manager

  Who knows what a manager really is? There can be more meaningful alternatives, such as Herder, Supervisor, Planner, builder.

• More words

  I.e. company_person stands for a company person

  It is more appropriate to rename company_person to staff, or update employee or director

• The passive voice

  i.e. PlanEvents

  It is better to rename PlanEvents to the initiative EventPlanner, or a further Scheduler

Level 2: Naming techniques

Increase your vocabulary

Naming is only part of writing, mainly vocabulary. You may remember that part of learning a foreign language is learning vocabulary. Not having to learn a foreign language has both advantages and disadvantages.

• Read open source, base library code
  • For example: Linux kernel, C++ STL library and so on
• Find business association concepts
  • For example, the skU:sku(Stock Keeping Unit); Search abbreviation:qv (Query View Count)

Better naming method

• Follow conventions, standards

  Do not use identifiers, but use industry convention ids as unique identifiers. Similar:

  • ptr 为pointerThe abbreviation of;
  • i,j,kOften perfect for loop counting variable naming.
  • size,capacity,resize,reserve,push,pop,top,backAs the container interface, the time-tested. To customize containers should not be usedGetSizeSuch as a name.

• To comply with the constraints

  • Language constraints: for example, Go language usagehumpStyle, don’t use C in your codeCapital and underline conjunctionsstyle
  • Team constraints: For the same concept, the team has a corresponding name, should follow, but not capricious with illicit goods, such as: live (ongoing vs living), has been namedongoing, or replace withliving; Just replace them all, or keep using themongoing“, although the latter is more accurate.
  • Framework constraints: UseShopify/saramaIt should be used as a kafka clientConsumer,ConsumerGroup,ConsumerGroupHandler, name the three levels instead of creating the three levels:Dao,Consumer,Processor

• Alignment, symmetry

  Align: Golang standard library package names, httpTest, Httputil, httpTrace

  Symmetry: Typical symmetry, Producer/Consumer, begin/end, create/destory, Destination /source, get/release, Increment/Decrement, INSERT /delete, Next/Previou S, old/new, old/new, open/close, put/get, show/hide, start/stop, target/source,

Level 3: Domain Language

People respond to names subconsciously… So if in doubt about a name, it can be difficult to say exactly why. Our design system should be named as expected. … But whose expectations? All stakeholders, stakeholders of the system, including but not limited to:

• The product manager
• Development (front end, back end, client)
• test
• The user

The code should automatically use the same name as the business or claim model. For example, if a travel business uses “venue” as a generic name for cafes, hotels, and tourist attractions, it would be a bad idea to use “place” in the code

• For one thing, communication becomes more complicated because two different languages are used
• Second, if a word can be intuitively understood by product managers and users who do not understand software development, then it is a good name
• Third, tie the code naming to the domain model, and all the naming fits the business
• Fourth, with the iteration of requirements, while polishing the domain model, it can ensure that the naming is reconstructed to conform to the semantics and keep the constant new

Using domain language to unify the development process can fundamentally explain the naming source and rationality. Compared to the general technique, it is systematic and theoretical. If skill is the product of engineering, domain language instruction naming is the product of academia.

How to implement DDD in the project will be explained in detail later.

Code word is not easy, like please three (like, comment, forward) support!