This article has participated in the third “topic writing” track of the Denver Creators Training Camp. For details, check out: Digg Project | Creators Training Camp third is ongoing, “write” to make a personal impact.

What is readable code? Is not only a novice developer anxiety, but also many years of development experience will be anxious about the problem. Here I will talk about my understanding from the aspects of code naming, code comments, design documents and so on. Write similar article for the first time, please give directions a lot!

Code name

Naming code can be a headache for Java developers because names are a matter of opinion. Different people have different interpretations. How to identify a good name? My answer is: “see the name know meaning, easy to understand”, use the most commonly used words and then reasonable combination.

The name of the class

Our class names are usually humped and capitalized. Example:

ForceCode // positive example ForceCode // negative exampleCopy the code

Method name and variable name

Method names, and variable names are humped in lower case, for example:

localValue / getHttpMessage
Copy the code

The package name

Note that package names are all lowercase and use singular words between separators. Example:

org.springframework.beans
Copy the code

Each layer naming reference

A) Service/DAO layer method naming convention

1) Methods that get individual objects are prefixed with get.

2) Obtain multiple object methods with list prefix, plural end, e.g. ListObjects.

3) Methods to obtain statistics are prefixed with count.

4) Insert methods prefixed with save/insert.

5) Delete methods with remove/delete prefix.

6) Update methods are prefixed with update.

B) Naming conventions for domain models

1) Data object: xxxDO, XXX is the name of the data table.

2) Data transfer object: xxxDTO, XXX is the name related to the business field.

3) Display object: xxxVO, XXX is generally the name of the web page.

4) POJO is a general name of DO/DTO/BO/VO. It is forbidden to name it xxxPOJO.

Code comments

Before starting to set up the code, we must first comb through the corresponding requirement logic first, it is best to form a document or flow chart and so on to develop, to do “think well”. Otherwise, if you do the back and forget the front, the code will pile up.

These key points can be noted in comments. Remember, “Comments are only supplementary descriptions of the key logic of the code.” I do not recommend writing long paragraphs in the code. These should be in the design document or written in the wiki.

There are three types of comments: document comments, line comments, multi-line comments, and tags.

What qualifies as a comment? I think comments that help the reader quickly understand what the developer is really saying are valid comments; In short, the ability to add descriptions at key code locations makes it easier for the reader to understand the code logic.

Documentation comments

The first thing you need to do for a Java file is to have a documentation comment, which I think basically says what the class does; Who wrote this class, or more than one person wrote it; As well as the creation time, modify the record and so on.

@date 2021-08-17 */ public class Test {}Copy the code

Comment line

A single line comment inside the method, with a separate line above the commented statement, using the // comment. Method internal multi-line comments using /* */ comments, note alignment with code.

Line comments are the most commonly used comments. When annotating must pay attention to the words must be simple, if English is not special standard try to use Chinese, so as not to mislead the reader. Finally, make sure to take a look at your own comments in code review to see if you can understand them, or when reading each other’s code to determine whether the comments can help readers read the code better.

Special comment mark

The most commonly used special markup is todo and fixMe. For this kind of markup, the reason for the markup, the markup person, and the expected processing time can be written clearly. Example:

// The order processing logic can not be abnormal rollback xx 2021-08-17Copy the code

Design document

I think most developers are in the same situation as me, “IT’s ok for me to write code, it’s totally hard for me to write documentation”. The reason why there is such a problem is that we feel that the logic we write is either messy, or we are not willing to comb through the logic of the previous function, or that the function is relatively simple. In fact, there are a lot of documents that are essential to our development process.

  1. Requirements Document (PRD)
  2. Database design document (E-R diagram)
  3. Design documentation (core function flow chart, data constraints, external dependencies)
  4. code
  5. Code review log
  6. The test case
  7. Operational log

The resources

  • www.zhihu.com/question/20…