Development of high-quality software for the platform Android is impossible without a competent structure and understandable code. When you're working on a project alone, writing explanations may seem like a waste of time, but after a couple of weeks you'll forget the logic behind how complex algorithms work. Comments in Android Studio serve as an invisible bridge between the algorithm and the developer, allowing you to quickly navigate thousands of lines of code.
This integrated development environment offers powerful tools for code annotation, ranging from simple one-line notes to complex technical documentation generation. Understanding how to properly use these tools is critical to maintaining cleanliness. In this article, we will look in detail at all the ways to create comments, from manual entry to automation using hotkeys. project. In this article we will look in detail at all the ways to create comments, from manual entry to automation using hotkeys.
Ignoring this part of programming often leads to the fact that the code becomes “spaghetti”, which is impossible for even the author to understand. Correct use of TODO and FIXME tags helps you plan tasks right inside the editor. We will cover not only the syntax, but also the best practices that will make your code professional and easily maintainable.
Basic syntax and comment types
In the Java and Kotlin programming languages, which are the main ones for development under Android, there are several types of annotations. The most common is the one-line comment, which begins with a double slash. The compiler ignores everything written after the characters // to the end of the line. This is an ideal way to quickly explain the effect of a specific variable or condition.
For longer descriptions that span multiple lines, block syntax is used. It starts with / and ends /. Inside such a block, you can write text of any length, break it into paragraphs, and even temporarily disable large sections of code during debugging. However, be careful: nested block comments can cause compilation errors if the nesting is not respected.
Use different colors for comments in the Android Studio theme settings to visually separate the explanations from the executing code.
Documentation comments have a special place. Javadoc. It begins with /** (two stars) and is used to generate external documentation. The IDE automatically recognizes this type and allows you to create descriptions of methods, classes and parameters, which can then be exported to HTML format. This is an industry standard for public API.
Hotkeys and automation in the IDE
Manually entering characters slows down the development process, so experienced programmers actively use keyboard shortcuts. It Android Studio provides a function for quickly commenting on a selected block of code. For Windows and Linux this is the combination Ctrl + /, and for macOS - Cmd + /. This command automatically adds or removes // at the beginning of each selected line.
If you need to comment out a block using characters /.. /, use the extended keyboard shortcut. On Windows it is Ctrl + Shift + /, and on Mac it is Cmd + Option + /. This function wraps a selected section of code in a block comment, which is useful for temporarily disabling entire methods or classes without removing them from the file.
☑️ Testing commenting skills
In addition to hotkeys, the development environment supports so-called Live Templates. You can customize your own abbreviations, which will be expanded into ready-made comment templates. For example, typing tcom and pressing Tab can instantly insert a copyright template or a standard license disclaimer. This saves time and ensures consistency of style throughout the entire project project.
Working with Javadoc documentation
Creating quality documentation is a sign of developer maturity. To generate a template for a method, just place the cursor in front of its declaration and press the key / twice (or /** and Enter). Android Studio will automatically create a block with tags @param for parameters and @return for the return values.
Inside such blocks, you can use HTML tags to format the text, for example, <b> for bold font or <ul> for lists. This allows you to create readable descriptions that appear when you hover over a method in other parts of the project. The IDE's hint system will show your text, helping other developers understand how to properly use your function.
| Tag | Purpose | Usage example |
|---|---|---|
| @param | Input parameter description | @param userId User ID |
| @return | Description of the return value | @return true if success |
| @throws | Description of possible exceptions | @throws IOException on error |
| @see | Reference to another method or class | @see UserManager |
| @deprecated | Deprecation notice | @deprecated Use v2 |
Javadoc Secrets
You can use the {@code} tag inside description text to highlight variable names or pieces of code in a monospace font without interrupting the documentation flow.
Describe why a method is needed, and not what it does, if this is obvious from the name. A good function name often replaces the need for lengthy explanations. Focus on describing business logic and edge cases.
Special labels and developer tasks
In the ecosystem Android there is a set of standard keywords that IDE highlights in a special color and displays in a special toolbar. These tags help manage work flow and track technical debt. The most famous of them is TODO, which indicates a task that needs to be performed in the future.
Label FIXME is used to indicate code that does not work correctly or contains a bug that requires an urgent fix. It is usually highlighted in red, attracting maximum attention. There are also tags NOTE for important notes and XXX for code that requires revision, but is not a critical error.
To see a list of all such tags in the project, open window TODO in the bottom toolbar or use file search. This allows you to instantly jump to the place where work is needed, without manually flipping through hundreds of files. Regularly reviewing this list helps keep your code clean and not to forget about planned improvements.
Customizing styles and colors
Visual perception of code plays a huge role in productivity. Default Android Studio colors comments green, but these settings can be changed to suit your needs. Go to the menu Settings (or Preferences on Mac), then select the section Editor → Color Scheme → General.
In the list of elements, find the item Comments. Here you can change the background color, text color, and even add an underline or italic effect. The style for Doc Comment (Javadoc) is separately configured, which allows you to visually distinguish documentation from ordinary service notes. Experiment with contrast to make your eyes less tired.
⚠️ Warning: Too bright or acidic colors for comments may distract from the main code. It is recommended to use muted shades of gray or green that do not create visual noise.
In addition, in the Code Style section you can configure automatic formatting. For example, you can tell the IDE to automatically add a space after a slash in single-line comments or to wrap long lines on a new line. This ensures a consistent writing style across the entire development team.
Best practices and common mistakes
The main rule of writing comments is: the code should explain itself. If you have to write a complex explanation for a simple block, it may be worth rewriting the code itself to make it more understandable. Comments should complement the code, explaining the reasons for making certain architectural decisions, and not duplicate syntax.
Avoid commented “dead” code. Many developers are lazy to remove an unnecessary method and simply close it in a block /.. /. This clogs up the project history and confuses colleagues. If the code is no longer needed, delete it. Version control systems such as Gitwill allow you to restore it at any time if necessary.
The comment should answer the question “Why?”, not “What?”. The code itself shows what is happening, and the comment explains the reason for this action.
Also try to update comments when the app logic changes. An outdated explanation that contradicts the actual behavior of the code is worse than no comments at all. It is misleading and forces you to waste time analyzing inconsistencies. Regular refactoring also includes checking the relevance of text descriptions.
FAQ: Frequently Asked Questions
How to quickly remove all comments from a file?
Android Studio does not have a built-in “delete all comments” button, but this can be done using the regular expression replacement function. Click Ctrl + R, enable Regex mode and use the pattern to find single-line and block comments, replacing them with an empty line.
Why is my Javadoc not showing up on hover?
Make sure you are using the correct syntax /** with two stars. A regular block comment /* is not processed by the documentation system. Also make sure that the comment is located immediately before the class or method declaration without empty lines between them.
Is it possible to write comments in Russian?
Yes, Android Studio fully supports UTF-8 encoding, so you can write explanations in any language, including Russian. The main thing is that your team agrees on using a common language for documentation to avoid problems with understanding.
How to add a comment author automatically?
You can use Live Templates. Create a new template with an abbreviation, for example, auth, and enter // Author: $USER$ Date: $DATE$in the text field. The IDE will substitute the $USER$ and $DATE$ variables automatically from the system settings.