Any Comments? Comment Your Code Like a Pro With IntelliJ IDEA
After reading the title of this post, many developers might think that it doesn’t make sense. Professional developers write their code in a way that it is clear and readable not only to them, but to any developers that deal with it in the future – without any comments. While this is true, if we’re completely honest, we know it isn’t always as easy as that in real life. So, let’s take a look at how you can comment your code quickly and efficiently.
There are various types of comments in code and not all of them imply that your code smells.
We can leave comments to clarify the code for ourselves, or for other members of the team, if the code is difficult to read or might require some work in future. In open-source projects, where multiple developers with different backgrounds work on the same thing, getting up to speed using comments can spare you a lot of time trudging through the code.
Comments can also be useful if you need to temporarily “hide” a piece of code without actually deleting it.
We also comment properties in .properties files if we localize our applications for other countries. This can be crucial if our properties contain concatenations or variables.
Whenever we notice room for improvement in code, we can leave ourselves, or others, TODO comments. Here we add quick notes on what can be changed without leaving the IDE.
Documentation comments is another type of comments in code. Take, for example, Javadocs (/**...*/). The best thing about them is that later on you can generate proper API references from these comments with just a few mouse clicks.
Javadocs deserve their own separate blog post as there are so many things to cover. So, let’s concentrate on clarification comments and TODO comments.
Line and block comments
Single-line comments in Java start with two forward slashes (//). To quickly add a line comment in IntelliJ IDEA, press ⌘ / on macOS or Ctrl + / on Windows and Linux.
Block comments or multi-line comments usually take the form of a paragraph. There are exceptions like when we need to insert a comment in the middle of the code line. In this case, using a multi-line comment is our only option no matter how short our comment needs to be.
Block comments are enclosed in slash-asterisk (/*) and asterisk-slash (*/). To add a block comment in IntelliJ IDEA, press ⌥ ⌘ / macOS or Ctrl + Shift + / on Windows and Linux.
IntelliJ IDEA has a quick-fix that can convert a line comment into a block comment and vice versa. Place the caret at the comment, press Alt+Enter on Windows and Linux or Option+Enter on macOS and select Replace with end-of-line comment or Replace with block comment.
Press F1 while the suggestion list is open to preview the change.
You can use the same shortcuts to uncomment commented lines.
You can generate comments at the beginning of the line or align them with your code. Additionally, you can configure the IDE to add spaces between the comment symbol and the text of the comment when you are adding new comments. In block comments, a space will be added before and after the text.
You can configure these settings in Preferences / Settings | Editor | Code Style | Java | Code Generation | Comment Code.
In the upcoming IntelliJ IDEA 2022.1, we’re adding a new feature that allows you to add a space in a line comment when you are reformatting your code in Java, Kotlin, and Groovy. You can already try it out in the latest EAP build.
TODO comments
TODO comments are useful when you notice a piece of code that needs some attention and you want to leave a note for yourself or for your team without leaving the editor.
By default, IntelliJ IDEA provides two predefined patterns: a comment containing TODO (//TODO) and a comment containing FIXME (//FIXME). You can create your own patterns using regular expressions. To do this, create a live template to quickly insert custom TODOs into your code.
IntelliJ IDEA gathers all the TODO comments in one tool window so you can be sure they don’t get lost in the codebase. They are also highlighted in the editor and marked on the error stripe on the right side of the editor. To view all TODO comments, select View | Tool Windows | TODO from the main menu.
And a nice bonus
As a bonus, IntelliJ IDEA automatically searches for grammar and spelling mistakes in your codebase in texts in natural languages. It can even warn you about inappropriate style. Press Alt+Enter / Option+Enter on an underlined word to see the available suggestions. Before trying this, make sure that the bundled Grazie plugin is enabled.
Comments in code have their uses. Sometimes they are just helpful, other times they are crucial. IntelliJ IDEA can help you leave as many comments as you think are necessary.
What do you think? Do you often leave comments in your code? Comment in the comments below.
Happy developing!
Subscribe to IntelliJ IDEA Blog updates
