The role and purpose of comments on Java development and some important aspects of code writing specifications and Java development specifications [Master Wang]

My detailed
explanation Author: Wang Wenfeng, who has participated in the CSDN 2020 blog star, "Java Wang Master Wang Tianshi" procurement supply chain sharing platform personnel, financial rule reconciliation personnel, logistics access control measurement system docking personnel, ERP business department staff Official account:
Shanfengcaotang , a number of non-technical articles, focusing on Java development issues, Chinese national studies, traditional culture, and program life for code lovers, looking forward to your attention and support! My nickname: Mysterious Xiaofeng, Shanfeng
Reprint instructions: Be sure to indicate the source (Note: Author: Wang Wenfeng)

1. The comment specification for writing code is as follows:

Comments should be concise, outlining what the code does and its purpose.

Comments should be on a separate line from code.

Comments should use correct grammar and spelling to make it easier for readers to understand.

Comments should avoid abbreviations or unnecessary abbreviations.

Comments should clearly explain the meaning and function of parameters and return values.

Comments should clearly describe what methods and functions do, how they are called, and how exceptions are handled.

Comments should follow a consistent format and style to make them easier for readers to understand.

Comments should be updated in time when the code changes to keep them timely and accurate.

Notes should be as concise as possible, avoiding overly descriptive and repetitive information.

Comments should be used to explain complex or non-obvious code, not simply repeat their meaning.

2. Detailed explanation with examples - show to understand the specification

When writing code, annotation conventions are very important for the readability and maintainability of the code. Here are some common annotation conventions:

1. File comment: Add a comment block at the beginning of the file, describing the content, author, creation date and other information of the file.

/*
   文件名：test
   描述：示例代码文件
   作者：王大师
   创建日期：2023-07-24
*/

2. Function comments: At the beginning of each function, use a comment block to describe what the function does, its input parameters, and its return value.

def add_numbers(a, b):
   """
   将两个数字相加并返回结果
   参数:
       a (int): 第一个数字
       b (int): 第二个数字
   返回:
       int: 两个数字的和
   """
   return a + b

3. Line Comments: Add comments at the end of lines of code, explaining the intent or key steps of the code.

result = add_numbers(3, 5)  # 调用add_numbers函数计算结果

4. Block Comments: For longer code blocks or logical paragraphs, use comment blocks to explain the functionality and implementation details of the code.

# 检查用户输入的有效性
if input_data:
   # 执行数据处理操作
   processed_data = process_data(input_data)
   # 显示处理后的结果
   display_result(processed_data)
else:
   print("无效的输入")

5. Comment style and formatting: Comments should use clear and concise language, avoiding redundant and ambiguous descriptions. Comments are kept in sync with the code and use proper indentation and typography.

# 计算阶乘的递归函数
def factorial(n):
   """
   递归计算给定数字的阶乘
   参数:
       n (int): 要计算阶乘的数字
   返回:
       int: 阶乘结果
   """
   if n == 0:
       return 1
   else:
       return n * factorial(n-1)

6. Update comments: If the code is changed or fixed, update the relevant comments in time to ensure that the comments are consistent with the actual code.

The above are some common annotation specifications, which can be adjusted and extended according to the needs of your own team or project. Remember, well-documented comments improve code readability and maintainability, facilitate teamwork and code reuse.

3. Some important aspects of Java development specifications:

Following are some important aspects of the Java development specification:

1. Naming conventions:

   • Class names: use uppercase camelCase, eg MyClass.
   • Method names and variable names: Use lowercase camel case, eg myMethod.
   • Constant name: Use all uppercase letters, and separate words with underscores, eg MAX_VALUE.
   • Package name: Use all lowercase letters, .separate multiple words, eg com.example.myproject.

2. Indentation and spaces:

   • Use 4 spaces for indentation and no tabs.
   • Use spaces appropriately to increase code readability, such as between operators, after delimiters, etc.

3. Annotation specification:

   • Use Javadoc comments to describe the functions, parameters, and return values ​​of classes, methods, and fields.
   • Use block or line comments to explain the intent and key steps of your code.
   • Comments should be clear, concise, and in sync with the code.

4. Class and method design:

   • Classes should have the Single Responsibility Principle and be responsible for only one clear functionality.
   • Methods should be named appropriately and follow the Single Responsibility Principle.
   • Avoid using long methods and classes, and try to keep the code concise and readable.

5. Exception handling:

   • Handle and catch exceptions appropriately, avoiding empty catch blocks.
   • Do not use exceptions to control the flow of your program.
   • Use a suitable logging tool to record exception information and other critical information.

6. Formatting and typesetting:

   • Use a consistent code formatting style, such as brace placement, line breaks, etc.
   • Appropriate blank lines can increase the readability of the code, such as between methods, between logical paragraphs, etc.

7. Import and package management:

   • Explicitly import classes and packages and avoid wildcard imports.
   • Organize the package structure of the code to avoid package name conflicts.

8. Concurrency and multithreading:

   • Use thread-safe classes and methods, or use synchronization mechanisms appropriately.
   • Avoid excessive use of locks and shared resources to reduce the risk of deadlocks.

9. unit test:

   • Write unit tests to verify the correctness of the code.
   • Use a suitable testing framework such as JUnit.

These specifications are only part of the Java development specifications, in fact there are many other aspects to consider

4. Summarize the role of comments

The role of code comments:

Provide documentation and understanding: Comments explain the function, purpose, and key steps of the code, helping others and themselves understand the intent and implementation details of the code.
Improve readability: Clear comments can make the code more readable and reduce the time cost of others to read and understand the code.
Easy maintenance and modification: Comments provide the context of the code, which can help developers quickly understand the function of the code, making it easier to maintain and modify.
Reduce errors and bugs: Comments can alert developers about known issues, limitations, or potential errors, helping to avoid common errors and bugs.
Improve teamwork: Standardization and consistency of annotations help team members collaborate better and improve team development efficiency.
All in all, following Java development specifications and good code commenting practices can improve code readability, reliability, and maintainability, and help team development and code reuse.
1. Master JAVA entry to advanced knowledge ( continuing writing... )
2. Learn Oracle database usage ( creating... )
3. Teach you how to make vbs scripts ( under perfection... )
4. Awesome IDEA Programming tool ( in writing... ) 5. Interview
skills for hematemesis ( updating... )

5. Summary of interview questions

 Chapter 1: Daily_JAVA_Interview Questions 15 (with answers)
 Chapter 2: Daily_JAVA_Interview Questions 14 (with answers)
 Encyclopedia of previous articles...

  The above is today's content, follow me, don't get lost.

 Interviewer of Ping An One Wallet: Please tell me about the implementation principle of Mybatis

 Java Development - Hot Spots - Summary of Hot Issues - Recommended

One-key triple, _{one-key triple,} one-key triple~

My detailed
explanation Author: Wang Wenfeng, who has participated in the CSDN 2020 blog star, "Java Wang Master Wang Tianshi" procurement supply chain sharing platform personnel, financial rule reconciliation personnel, logistics access control measurement system docking personnel, ERP business department staff Official account:
Shanfengcaotang , a number of non-technical articles, focusing on Java development issues, Chinese national studies, traditional culture, and program life for code lovers, looking forward to your attention and support! My nickname: Mysterious Xiaofeng, Shanfeng
Reprint instructions: Be sure to indicate the source (Note: Author: Wang Wenfeng)