31

To represent keywords while writing Java Docs should I use the <code> element or the <tt> element? Are there specific situations when one should be preferred over the other?

Andrew Thompson
  • 168,117
  • 40
  • 217
  • 433
Geek
  • 26,489
  • 43
  • 149
  • 227

5 Answers5

34

For inline code in Javadocs,you should use {@code your-code-here}

See javadoc - {@code text} for more details.

Equivalent to <code>{@literal text}</code>.

Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. ..

Community
  • 1
  • 1
Cephalopod
  • 14,632
  • 7
  • 51
  • 70
  • 5
    On reflection, while having answered the question that was asked, this answers the question that *should* have been asked. "How to represent code for the JavaDoc tool?" For that, it would we worth a few more than the single up-vote it has got. Great answer & thanks for the tip. :) – Andrew Thompson Jan 26 '13 at 15:58
20

From the W3C on TT.

HTML Reference

The element is a non-standard element.

HTML5 classifies it as a non-conforming feature.

Examples

No, really, don't use it.

And I think that answers the question. Choice of 2 elements, W3C says do not use one of them.

Community
  • 1
  • 1
Andrew Thompson
  • 168,117
  • 40
  • 217
  • 433
  • Weird that Java docs 7 still uses it e.g. http://docs.oracle.com/javase/7/docs/api/java/lang/ClassLoader.html – Pacerier Aug 25 '14 at 15:47
  • @Pacerier I OTOH, am not the least bit surprised. Sun/Oracle are not authorities on HTML. – Andrew Thompson Aug 25 '14 at 15:51
  • 2
    Yes, yet `` seems to work on every single browser and has > 99.99% chance to continue to do so in the future *regardless* of what W3C says (while history has shown us that W3C isn't entire sure of where the future is going (starting with their xhtml nonsense) and their *future* recommendations often conflict with their previous ones (even for simple things like and http://stackoverflow.com/questions/271743/whats-the-difference-between-b-and-strong-i-and-em#comment-8254050 ). So besides W3C's words, what are some *objective* reasons against using ``? – Pacerier Aug 25 '14 at 16:07
  • @Pacerier 1) Everything that can be achieved using that text can be achieved using the `` tags. 2) The `code` element ***is*** part of an HTML standard. 3) 100% of User Agents claiming to conform to an HTML standard will support (and supposedly fix bugs related to the rendering of) the `code` element. Would you use a deprecated Java method, or the one that replaces it? -- Now give me 3 'objective' reasons you might use this entirely redundant, non conforming element? – Andrew Thompson Aug 25 '14 at 16:21
  • 2
    **1)** Not everything that can be achieved using `` can be achieved using ``. The semantic meaning of `` is teletype fixed-width. The semantic meaning of [``](http://goo.gl/LI9JbT) is "code" (yea that "code" which relates to *programming* / *computers* etc). Now what if we want to indicate teletype fixed-width non-code words? It doesn't seem to be a good solution to hijack `` to indicate teletype fixed-width words which are non-"code". Thus, we use ``. **2)** Your point 2 is a non-argument. Yea, it's part of an HTML standard, yet "part of a standard"........... – Pacerier Aug 25 '14 at 16:58
  • 1
    ...... *by itself* is not an objective reason; requires elaboration. **3)** So this seems to be your elaboration from point two. Allow me to repeat: `` works on 100% useragents and has > 99.99% chance to continue to do so in the future. Now, let me ask you a simple **question:** Is 100% of useragents more or less than 100% of conforming-useragents? **4)** Comparing "deprecated Java method" to `` is a stark example of [strawman fallacy](http://goo.gl/IpvQSF). `` has a 99.99% chance of future full-support. Does Java deprecated methods have a 99.99% chance of future full-support? – Pacerier Aug 25 '14 at 17:00
  • 1
    @Pacerier I'm done arguing about it. If you want to use the `tt` notation, go right ahead. Better still, enter your own answer on the benefits of `tt`. – Andrew Thompson Aug 25 '14 at 17:06
  • 1
    This was never a debate, I'm merely seeking the **real** advantages/disadvantages of `` vs ``. You know, not comments like W3C is cool, W3C is hot, they can't be wrong, whatever they say is right because I like them. Or comments like [W3C is authoritative](http://en.wikipedia.org/wiki/Argument_from_authority), W3C is *big*, so whatever they say is right even if it's ["2+2=5"](http://www.youtube.com/watch?v=EHAuGA7gqFU). – Pacerier Aug 25 '14 at 17:38
7

The code tag is preferred as tt is a font style element and as of HTML 4, styling by style sheets is preferred to font style elements.

JamesB
  • 7,774
  • 2
  • 22
  • 21
3

There is little practical difference between code and tt, i.e. software that processes HTML documents treats them the same way: they are by default treated as inline elements, rendered in a browser-dependent monospace font and possibly (depending on browser) in reduced font size. A distinction between them is mostly just theoretic talk. However, some automatic translation software makes a difference, treating code as having non-translatable content.

So there is some advantage in using code, but it is more important that you consider the real implications of either markup. If you don’t want reduced font size, set font-size: 100%. If you don’t want browser’s default monospace, which tends to be Courier New, set font-family.

Jukka K. Korpela
  • 195,524
  • 37
  • 270
  • 390
  • seems great for javadoc code, I just discovered it looking at the Comparator.java source... it's littered with .. with it would be much more verbose and harder to read... I really like it - and I guess if it's good enough for the javadoc sources, it's good enough for me) – ycomp Sep 30 '15 at 15:12
  • 2
    @ycomp {@code List} is shorter than List and when you start adding special characters it is even more of a win: {@code List} is more readable/maintainable than List<string> – djb Jun 01 '16 at 19:35
0

To provide more information about the subject:

In my case I added an ASCII flow in my class javadoc and I had to use this to keep a monospace rendering:

/**
 * <pre>{@code 
 * flow here
 * }</pre>
 */

I just verify it in my IDE popup. I guess it will work in an HTML page...

Martin P.
  • 654
  • 8
  • 18