0

I've seen method references in PRs and comments and documentation but it's unclear what the specific symbology means.

E.g. ClassName#myMethod or ClassName::myMethod or what about ClassName::CONSTANT

Is there a distinction in the # and :: notation, does it say whether one method is an instance method, a static method, a variable, etc.?

Are there any other notations that can help me write cleaner pull request summaries, documentation or commit messages when referring to classes/methods and instance variables/constants? While also allowing me to be specific on typing and syntax when referencing the code?

3
  • 1
    This depends on the language. For example, the Ruby convention is to use MyClass::my_class_method or MyClass.my_class_method, and MyClass#my_instance_method.
    – Alexander
    Mar 5, 2021 at 1:49
  • 1
    Which language are you talking about and which documentation system? The examples you showed mean different things in different languages, they may even mean different things in different documentation systems for the same language. In some languages, none of the examples you showed is used. For example, in Smalltalk, you would write ClassName>>myMethod. Mar 5, 2021 at 13:48
  • What I'm learning here is that it's not that simple a question after all. Seeing all these different symbols have always confused me but I figured I was just out of the loop and there was a convention I was missing out on.
    – GoldFlsh
    Mar 5, 2021 at 14:24

1 Answer 1

6

There's no convention for this when it comes to pull requests; I suggest to stick to whatever the project is currently using. It's consistency that brings clarity in cases like this.

Some languages support generating documentation from comments, and it's often possible to link to another method in that documentation. But how depends on the programming language or the documentation system you're using. Here are two I'm familiar with; it's certainly possible to come up with other examples.

  • Java uses #: https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#@see. Instance/static method or field doesn't matter; the latter can be distinguished by not having parentheses. Here is part of the source code:

    3038       /**
    3039        * Returns the string representation of the <code>double</code> argument.
    3040        * <p>
    3041        * The representation is exactly the one returned by the
    3042        * <code>Double.toString</code> method of one argument.
    3043        *
    3044        * @param   d   a <code>double</code>.
    3045        * @return  a  string representation of the <code>double</code> argument.
    3046        * @see     java.lang.Double#toString(double)
    3047        */
    3048       public static String valueOf(double d) {
    3049           return Double.toString(d);
    3050       }
    

    and this is the resulting documentation. Note that you can click on the link in the "See Also" section. On the other hand, line 3042 uses a dot, just like when you call a method or field directly in the code itself. And to make it worse, :: is sometimes used in code as well, see Method References and scroll down to "Kinds of Method References".

  • C# always uses a .: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#see, also when a method, field or property is called in the code itself.

The dot is probably also the most widespread operator to denote methods, fields, properties and constants in object-oriented programming languages. If you really want a solution, I'd go for this.

2
  • 1
    Doxygen, commonly used with C++ uses :: which is the language semantic when accessing a class method without an object. Or namespace members
    – jaskij
    Mar 5, 2021 at 12:41
  • Thanks @Glorfindel my assumption was there was a convention that was spelled out somewhere that gave these symbols meaning to allow for simple short-hand when discussing specific code fragments. But it seems that there isn't a one-size fits all answer for this one.
    – GoldFlsh
    Mar 5, 2021 at 14:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.