Same. My vote would certainly go to /*** */, and dropping the leading * on the intermediate lines while you're at it. Or go with an alternative like /*# and # o

Same. My vote would certainly go to /*** */, and dropping the leading * on the intermediate lines while you're at it. Or go with an alternative like /*# and # on intermediate lines, because the demand for whitespace clarity is certainly bigger in markdown. I'm very used to consider line and block comments semantically different. To my mind block is javadoc (or for text addressed at the reader that is not meant for tools, in short for prose) whereas // is for killing source lines (and for killing block comments for tools). With the corollary that // would be absent from perfectly clean code, that removal of // is never wrong. In my own projects, I even add an exception mechanism for // that should be kept, they can be marked with ///*why*/, and why should better be good. "why" can be a key further explained in a regular block comment, the idea is that those lines can be cleanly enabled/disabled/removed with regex. On a very abstract level, I could describe my position as "languages should have multiple forms of comments that have clearly defined semantic differences". I consider this a paradigm change similar to how modern languages have started to declare one style guide the blessed one, even if technically whitespace is just as insignificant as in the old days of "do what you think is best". What I do miss, from the old doxygen days, is support for trailing comments for when you want to add a few short words to a field without begging for attention too much. Something like int count = 0; /** quuxes encountered */ And for inline javadoc in multiline argument lists, which I believe to become ever more common in the postOOP age. These could be implicit @param in the slurp javadoc, just like the markdown lists in the future work part of the JEP (where I to see a real benefit of magic headline/list pairs over repeated @param or @throws): void slurp( /** quuxes ready to be slurped */ int todo, /** quuxes slurped before */ int done ) { (Of course I'm mostly looking at KDoc here, where they already have markdown but where multiline parameter lists are even more common than in current/future java)