1

I often find it helpful to use KDoc/Javadoc comments inside of a class or function instead of normal comments. IntelliJ colorizes them more obviously by default and, more importantly, allows hyperlinking to definitions. I'm wondering if it is considered bad practice to do so.

For example:

/**
 * Standard kdoc comment here...
 */
fun saveUser(user: User) {

    /**
     * Save the user to the [UserRepository]
     */
    userRepo.save(user)
}

In the inner comment, [UserRepository] will be linked to the type definition for that class. This example is a bit forced, but I often find it helpful in read code.

Matt Robertson
  • 113
  • 4

2 Answers2

3

You ask "is it considered bad practice", and the answer is Yes.

But not so much because of using KDoc/Javadoc syntax in an inappropriate place, but because of the level of commenting. If you feel compelled to comment your code inside some method, think about rewriting it to achieve better readability.

In your example

fun saveUser(user: User) {

    /**
     * Save the user to the [UserRepository]
     */
    userRepo.save(user)
}

your comment is redundant. To any sane developer, userRepo.save(user) is perfectly readable as "save the user to the repository", so the comment can simply be deleted.

You talk about the linking possibilities. On the userRepo variable, any decent IDE will show you its declared type and let you navigate to the variable definition and to the class source, so this linking also isn't necessary (and it will only work with a non-standard IDE that accepts KDoc/Javadoc in places beyond the specification).

Of course, there might be situations where your comment isn't as trivial as in your example. But then, if your code is so obscure that it needs such a comment, you'd better rewrite it, or restructure it to call smaller methods with sensible names and the opportunity to add KDoc/Javadoc there.

Ralf Kleberhoff
  • 5,891
  • 15
  • 19
2

It's just not useful to do that. The purpose of KDoc or JavaDoc is to run a tool to generate HTML documentation for how to use your code. They way the tool works is it scans for the specially formatted comments in specific locations (i.e. method declarations and class declarations).

Depending on the tool used to scan for those comments you have two potential possibilities:

  • The scanner gets confused and generates erroneous documentation
  • The comments are ignored and simply treated like normal comments

My recommendation is to simply use regular comments inside your methods/functions. Standard multiline comments in many languages look like this:

/* This is a multiline
 * comment
 */

In fact the Javadoc notation is a standard multiline comment so it can be ignored by the compiler, and the extra * is there to call out that this comment is used for the tool that generates documentation pages.

Berin Loritsch
  • 45,784
  • 7
  • 87
  • 160
  • It is useful to do that though, because it allows me to hyperlink variable and type definitions, which standard comments don't allow me to do. But the recommendation against confusing the tooling is a good point. – Matt Robertson Jul 20 '21 at 18:17
  • 1
    @MattRobertson how exactly do standard comments "not allow" you to do that? You can use exactly the same hyperlink syntax. It won't be formatted into an actual hyperlink, sure, but that will not happen anyway, even if you use a Javadoc comment, because it's in the wrong place. But it will be exactly as helpful to human readers of the code. – Michael Borgwardt Jul 21 '21 at 11:03
  • @MichaelBorgwardt That's my point - it *is* formatted into an actual hyperlink, even though it's in the wrong place. I can command-click the hyperlink in the fake-javadoc-comment and jump straight to the type definition. I can't do that in a standard comment. So that bit is extremely helpful, I'm just asking if it's considered bad practice in spite of being helpful. – Matt Robertson Jul 21 '21 at 17:18
  • 1
    @MattRobertson: Ahh, now I get it, you are talking about IDE functionality... yeah, that has some value. – Michael Borgwardt Jul 21 '21 at 19:30