3

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.

  • 2
    Unfortunately, this is basically an opinion poll, which isn't so great on a StackExchange site. If the people who will be using this documentation do get properties and methods mixed up all the time, maybe the # thing helps. If not, maybe . is better because it's the same syntax as the language. No way for us to know which is more useful for your audience. – Ixrec Dec 6 '15 at 18:06
  • 2
    Without specifying a language, I think this question is too broad - it's almost certain that different languages will use different conventions and all those conventions are "right". – Philip Kendall Dec 6 '15 at 18:43
  • But on the other hand, documentation should be language agnostic? A "field" and a "method", "type" et cetera, is more or less the same thing in all languages too. – Martin Andersson Dec 6 '15 at 18:56
  • Presence of two parentheses is enough for me – paparazzo Dec 6 '15 at 19:38
6

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.

  • 2
    This only applies to Java, but the question seems to be language agnostic! E.g. this advice is totally inadequate for C++ or Perl where a different convention exists. – amon Dec 6 '15 at 18:35
  • @amon well, from his sample code I figured that his question applies to java. There is no language-agnostic tag, so I supposed that the lack of a java tag must be an omission. But I may be wrong. – Mike Nakis Dec 6 '15 at 18:38
  • 1
    Could you clarify who the "we" is in your last paragraph? – Philip Kendall Dec 6 '15 at 18:38
  • The only mention of Java in the question is “Java code only for the sake of example” at the very top … – amon Dec 6 '15 at 18:38
  • @PhilipKendall well, me, and other programmers that I have heard complaining about the general crappiness of the javadoc standard. – Mike Nakis Dec 6 '15 at 18:39
4

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.

  • Thank you for your answer. However, I don't agree that Mike Nakis "wrote an excellent Java centric response". The # symbol is used by the JavaDoc tool to generate links to other symbols, and must go into @-tags, such as @link, @linkplain and @see. Basically, the answer he put forth has nothing to do with the question; how to make references in text-based software documentation, whether that be outside a code base or inside a code base. Simply put it, which syntax to use to better describe the type of the symbol for the end user, a human. Like in this text box for example. – Martin Andersson Dec 7 '15 at 1:49
  • The end user will be accustomed to reading and writing JavaDocs, so his answer correctly explained the convention, and it's origin in the limitations of the JavaDoc syntax. As such, in the convex of the Java language and user base, I consider it an excellent answer. This is, of course, only my opinion, and you are free to evaluate it under such criteria as you prefer. – Morgen Dec 7 '15 at 3:53
  • Can you tell me where in his source does it say that a hash character is supposed to /** go anywhere in here */? – Martin Andersson Dec 7 '15 at 4:11
  • He doesn't. Possibly because there is no good reason to put a method reference without enclosing it in @link tag, if for no other reason than it's less likely to be missed by refactoring tools. – Morgen Dec 7 '15 at 4:38
  • There are "other reasons". For example, my first reference to a method is usually put in a @linkplain tag. Ensuing repetitive references are made in plaintext, often wrapped in a @code tag. The first tag is the one creating a blue hyperlink in all JavaDoc views, the rest of them doesn't all need to be links. Also, to turn back to the original question, the references to my symbols are made everywhere. Not only in what we define as JavaDoc: source-code comments. Text files. StackOverflow comment boxes. Furthermore, I use NetBeans and NetBeans can find and refactor names in comments too =) – Martin Andersson Dec 7 '15 at 13:58

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