Multi-line comments should be clear, useful, and not wordy, and are often used to explain complex logic or file functions. 1. Applicable scenarios include explaining the functions, parameters, return values and module uses of complex functions; 2. The format varies by language, such as """ for Python, and /.../ for Java. It is recommended to write content at the top, segmented blank lines, and use concise statements to express intentions; 3. Avoiding problems include general comments, disconnection from the code, using comments to block codes, and affecting document generation, and ensuring that comments are accurate and compliant with specifications.
When writing multi-line comments, many people actually don’t pay much attention to how to use them. In fact, multiple lines of comments are not just about writing a bunch of words. If you use them well, you can help you understand the code, but if you use them poorly, it will make you more confused. The key is to be clear, useful, and not talkative.
When should I use multiple lines of comment?
Multi-line comments are most commonly used to explain a piece of code with more complex logic, or to write them at the beginning of a file to explain the role of the entire file. For example, if you write a more circumferential function and want to explain its function, input and output, or why it is designed like this, it is appropriate to comment multiple lines at this time.
In addition, some development specifications require that the function be given annotation description, including parameters, return values, exceptions, etc., in this case, multi-line comments are also particularly practical.
- For example, when writing a tool function, you can first write a comment to explain the function.
- Or write an explanation at the beginning of the module to explain clearly what this module is for.
- Sometimes, a large piece of code will be temporarily blocked with multiple lines of comments, and for debugging
How to write the format of multi-line comments?
The writing of multi-line comments in different languages is different. For example, Python has three quotes """ and Java and C are /* ... */ . But no matter which one, neat format is the most important.
A common practice is:
- Write the comment content at the top, don't be too many
- If segmented, the empty line is clearer
- Use concise sentences to explain the intention, without writing "nonsense"
For example, in Python, you can write it like this:
""" This is a data cleaning function that mainly does three things: 1. Remove blank lines 2. Convert field type 3. Handle missing value parameters: - data: The input raw data is a dictionary list return value: - Return the cleaned data """
In this way, others will know what this function is for and how to use it at a glance.
What common mistakes should be avoided?
Many people tend to fall into several pitfalls when writing comments, such as:
- The comments are written too general, such as just writing "This is a function" but not saying what it is for.
- The comments are out of touch with the code, the code is changed but the comments are not changed, which misleads others.
- Comment out the code with multiple lines of comment, but I forgot to delete it, which makes the code look messy
Another thing that is easy to ignore is that some IDEs or document generation tools rely on multiple lines of comments to generate explanatory documents. If you write too casually, the tools will not be able to capture key information.
So suggestion:
- After writing the code, look back to see if the comments are accurate
- Don't write comments that have "have expired"
- If it is used to generate documents, it is best to write according to the project specifications
Basically that's it. Multi-line comments seem simple, but if you really want to write them clearly and usefully, you still have to think more about how others use your code.
The above is the detailed content of Proper Use of Multiline Comments. For more information, please follow other related articles on the PHP Chinese website!
Hot AI Tools
Undress AI Tool
Undress images for free
Undresser.AI Undress
AI-powered app for creating realistic nude photos
AI Clothes Remover
Online AI tool for removing clothes from photos.
Clothoff.io
AI clothes remover
Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!
Hot Article
Hot Tools
Notepad++7.3.1
Easy-to-use and free code editor
SublimeText3 Chinese version
Chinese version, very easy to use
Zend Studio 13.0.1
Powerful PHP integrated development environment
Dreamweaver CS6
Visual web development tools
SublimeText3 Mac version
God-level code editing software (SublimeText3)
Hot Topics
css dark mode toggle example
Jul 30, 2025 am 05:28 AM
First, use JavaScript to obtain the user system preferences and locally stored theme settings, and initialize the page theme; 1. The HTML structure contains a button to trigger topic switching; 2. CSS uses: root to define bright theme variables, .dark-mode class defines dark theme variables, and applies these variables through var(); 3. JavaScript detects prefers-color-scheme and reads localStorage to determine the initial theme; 4. Switch the dark-mode class on the html element when clicking the button, and saves the current state to localStorage; 5. All color changes are accompanied by 0.3 seconds transition animation to enhance the user
VSCode settings.json location
Aug 01, 2025 am 06:12 AM
The settings.json file is located in the user-level or workspace-level path and is used to customize VSCode settings. 1. User-level path: Windows is C:\Users\\AppData\Roaming\Code\User\settings.json, macOS is /Users//Library/ApplicationSupport/Code/User/settings.json, Linux is /home//.config/Code/User/settings.json; 2. Workspace-level path: .vscode/settings in the project root directory
css dropdown menu example
Jul 30, 2025 am 05:36 AM
Yes, a common CSS drop-down menu can be implemented through pure HTML and CSS without JavaScript. 1. Use nested ul and li to build a menu structure; 2. Use the:hover pseudo-class to control the display and hiding of pull-down content; 3. Set position:relative for parent li, and the submenu is positioned using position:absolute; 4. The submenu defaults to display:none, which becomes display:block when hovered; 5. Multi-level pull-down can be achieved through nesting, combined with transition, and add fade-in animations, and adapted to mobile terminals with media queries. The entire solution is simple and does not require JavaScript support, which is suitable for large
css full page layout example
Jul 30, 2025 am 05:39 AM
Full screen layout can be achieved using Flexbox or Grid. The core is to make the minimum height of the page the viewport height (min-height:100vh); 2. Use flex:1 or grid-template-rows:auto1frauto to make the content area occupy the remaining space; 3. Set box-sizing:border-box to ensure that the margin does not exceed the container; 4. Optimize the mobile experience with responsive media query; this solution is compatible with good structure and is suitable for login pages, dashboards and other scenarios, and finally realizes a full screen page layout with vertical centering and full viewport.
How to handle transactions in Java with JDBC?
Aug 02, 2025 pm 12:29 PM
To correctly handle JDBC transactions, you must first turn off the automatic commit mode, then perform multiple operations, and finally commit or rollback according to the results; 1. Call conn.setAutoCommit(false) to start the transaction; 2. Execute multiple SQL operations, such as INSERT and UPDATE; 3. Call conn.commit() if all operations are successful, and call conn.rollback() if an exception occurs to ensure data consistency; at the same time, try-with-resources should be used to manage resources, properly handle exceptions and close connections to avoid connection leakage; in addition, it is recommended to use connection pools and set save points to achieve partial rollback, and keep transactions as short as possible to improve performance.
Full-Stack Web Development with Java, Spring Boot, and React
Jul 31, 2025 am 03:33 AM
Selecting the Java SpringBoot React technology stack can build stable and efficient full-stack web applications, suitable for small and medium-sized to large enterprise-level systems. 2. The backend uses SpringBoot to quickly build RESTfulAPI. The core components include SpringWeb, SpringDataJPA, SpringSecurity, Lombok and Swagger. The front-end separation is achieved through @RestController returning JSON data. 3. The front-end uses React (in conjunction with Vite or CreateReactApp) to develop a responsive interface, uses Axios to call the back-end API, and ReactRouter
Java Performance Optimization and Profiling Techniques
Jul 31, 2025 am 03:58 AM
Use performance analysis tools to locate bottlenecks, use VisualVM or JProfiler in the development and testing stage, and give priority to Async-Profiler in the production environment; 2. Reduce object creation, reuse objects, use StringBuilder to replace string splicing, and select appropriate GC strategies; 3. Optimize collection usage, select and preset initial capacity according to the scene; 4. Optimize concurrency, use concurrent collections, reduce lock granularity, and set thread pool reasonably; 5. Tune JVM parameters, set reasonable heap size and low-latency garbage collector and enable GC logs; 6. Avoid reflection at the code level, replace wrapper classes with basic types, delay initialization, and use final and static; 7. Continuous performance testing and monitoring, combined with JMH
A Guide to Java Flight Recorder (JFR) and Mission Control
Jul 31, 2025 am 04:42 AM
JavaFlightRecorder(JFR)andJavaMissionControl(JMC)providedeep,low-overheadinsightsintoJavaapplicationperformance.1.JFRcollectsruntimedatalikeGCbehavior,threadactivity,CPUusage,andcustomeventswithlessthan2%overhead,writingittoa.jfrfile.2.EnableJFRatsta
