6

Assuming I have this class (Java code only for the sake of example):

class Person {
    private String name;

    public void setName(String name) {
        this.name = name;
    }
}

When I write documentation for this application and/or in-code documentation, what should I use to refer to a particular symbol, whether that be type, method or field?

When I describe a type, I usually say just "Person", keeping the casing of the type. When I refer to a method, I always do a dot: "Person.setName()". Depending on context, I might add the parameter list in order to be technically correct: "Person.setName(String)". I do not change the notation whether or not the method is static.

But field is a bit harder and I am not sure, despite being a programmer for many years now, that I have understood this part correctly. My heart want to always use a hash character: "Person#name". But I believe some of us use one or the other depending on context, whether or not the field is a static? And if so, which character to use when?

If dot is used, then the only disambiguation that exist between a field- and method reference is the presence of two parentheses, which in my mind is not enough. For example; "Person.name" is syntactically similar to "Person.setName()". But there's no commonality, in terms of special characters, between "Person#name" and "Person.setName()". Also, to my point.. is the fact that many of us are sloppy and actually refer to methods without parenthesis making the ambiguity absolute.

Also, if dot is supposed to be used in reference of a field, then some paragraphs of text will become rather awkward to read. For example:

Person is a class used in our application. A person has a Person.name. A person may also die.

Note that "name" is surrounded by a dot explosion. Versus:

Person is a class used in our application. A person has a Person#name. A person may also die.

All feed back is welcome. The answer that has a legit source or otherwise speak of community best practices is accepted. Me personally, I've googled but found nothing.

jus1in
  • 5
Martin Andersson
  • 176

2 Answers2

7

Actually, it is not an opinion poll, there is a clear answer mandated by the guidelines for writing doc comments, and followed by IDEs.

From your sample code it is obvious that you are talking about Java.

You pretty much have to use '#', since that's what is mandated by the standard, (see Oracle: How to Write Doc Comments for the Javadoc Tool) and that's the only way your doc comment will be understood by your IDE, so that when you hover the mouse over a function call you can see a nice tooltip explaining to you what the function does, what parameters it accepts, and what value it returns.

Oracle's standard is a bit outdated, and we would very much like to see it replaced by something more modern, but until that happens, hashes are the way to go.

Mike Nakis
  • 32,803
7

Mike Nakis wrote an excellent Java centric response.

For other languages, you need to follow the similarly established conventions.

Ruby, as an example, uses "::" for class methods, and "#" for instance methods.

The point, however, is simply this: you are not writing the documentation for only your personal consumption, but for other programmers. Learn the conventions and standards for the language you are using and stick to them.

Morgen
  • 1,081