[Solved] What are the guidelines for referring to Java methods?

by


Assuming this question is referring to the difficulty of how to refer to methods when talking about Java code in a meta context. E.g.

You should use the StringBuilder.append() method instead of the ++ operator in this context because…

Now, a method we could talk about can be categorised in the following ways:

  • static vs non-static
  • has arguments vs has no arguments
  • has return value vs has void type
  • public vs private vs other access

The above example is enough, in context, to be unambiguous, since there is no great overlap between methods named ‘append’. However, if it were lifted into some actual Java code, it could not possibly compile, for several reasons:

  • the ‘append’ method in question requires an argument
  • it is a non-static method, and the usage above looks like a static method call.

In addition, because it is written like a static method call, but refers to an instance method call, the reader could be confused.

In a lot of contexts, a solution can often be found which removes all ambiguity by giving an actual code example.

Try this approach:

StringBuilder sb = new StringBuilder();
sb.append(textToAppend);

The problem with this is unnecessary wordiness, and it becomes a little more unwieldy and inconvenient. In addition, it loses the ability to discuss methods in a ‘meta’ way, and there’s no obvious place to put links for reference.

If the class of the method you are referring to is known, one way to remove all ambiguity is to give the full method signature as given in the Java API Specification, including access modifiers. E.g.

Try using the public StringBuilder append(String str) method of an instance of StringBuilder. This avoids repeating the process of…

This has the advantage of consistency, and of displaying all of the relevant information, but it does become more effort to type.

If the context means there is no ambiguity, it is reasonable to omit any of the following:

publicStringBuilder append(String str)

You can omit public if the access modifier is not relevant to the discussion.

publicStringBuilderappend(String str)

You can omit the return type if it is obvious, or unambiguous, or not relevant to the discussion.

public StringBuilder append(Stringstr)

You can omit parameter names if they aren’t relevant to the discussion (normally the case).

public StringBuilder append(String str)

You can omit parameters altogether if there’s no ambiguity in the intention or they aren’t relevant.

Try using the append method of an instance of StringBuilder. This avoids repeating the process of…

This is perhaps the most unambiguous approach while avoiding unnecessary information. That said, the notation in my very first example is very convenient and often will not lead to confusion.

In the end it’s down to a matter of taste, but avoiding ambiguity should be the most important consideration, and to that end, adopting an approach relatively in line with the Java API specification itself seems a good idea.

solved What are the guidelines for referring to Java methods?