[rdf4j-dev] code formatting: section marker comments

["Jeen Broekstra" <jeen@xxxxxxxxxxxx>]

This recently came up as part of a PR and I wanted to hear some opinions. None of this is shocking or urgent, but it might pay off to collect some thoughts and hear some suggestions, see if we can come up with a best practice.

In the older parts of the code base, we used to use comment markers to indicate "sections" in Java files, for example:

/*--------------*

 * Constructors *

 *--------------*/

and

/*---------*

 * Methods *

 *---------*/

etc.

However, over the years this practice has slipped: most of us don't actively add such section markers in new code anymore, and I've also noticed that in several places we've ignored these markers, sticking variables in the constructor section, mixing private and public methods, etc etc. Recognizing this, I've personally started just removing these marker comments whenever I encounter them: better no markers than markers that are inconsitent/make no sense.

Allesandro, in his PR for refactoring the AbstractValueFactory, used another option to visually separate sections, basically just adding a long string of slashes:

  /////////////////////////////////////////////////////////////////////

He mentioned that he finds it helpful to visually organize code this way, and I can see his point. I don't particularly mind doing something to mark out sections: it can be helpful in larger Java files to impose some organization, stick public methods together, have constructors at the top, etc. But if at all possible I'd like us to use one shared, consistent way of doing this.

So the question: do we want to adopt a particular style for this kind of thing? I am not suggesting that we mandate that we start using this in every single code file, just that if you have a larger Java file and want to use some markers to organize it, we use a particular, agreed-upon marker style.

I personally am not a fan of the old ASCII-art box shown above: it is just too cumbersome to write it from scratch every time and make sure it's properly formatted. If we mandate that kind of formatting, it will just get quietly dropped. We need something easier.

I also don't particularly like the line of slashes to be honest, as it doesn't tell you anything about the section, and also (to me at least) is visually very distracting.

So how's this as a simple, easy to read, marker comment:

  /* Section: Constructors */

 /* Section: Interface1 overrides */

Simple to write and customizable (and also shows one perticular use of sections that I personally like: to group method overrides from a particular superclass or interface together). I am deliberately choosing /* */ over // to distinguish it from comments that are just remarks about the next line. Empty line before it, and after it, to single it out.

Your thoughts? 

Finally: I am deliberately ruling out using anything like automated code folding markers or other editor-specific functionality, such as IntelliJ's  //<editor-fold "magic comment" or Eclipse's @category javadoc tag. I don't want us to rely on a particular editor choice as it just makes life harder (without any payoff) for anyone not using that particular editor.

Cheers,

Jeen