Re: [rdf4j-dev] code formatting: section marker comments

["Jeen Broekstra" <jeen@xxxxxxxxxxxx>]

On Sat, Nov 7, 2020, at 22:01, Håvard Ottestad wrote:

Reading some old code without any comments for variable names makes it particularly evident that good organization and helpful comments is useful to understanding what the intentions were later on. 

Quite.

I’m not a big fan of having to organize variables in sections. I am a fan of deciding if variables should go before or after constructors though (I prefer before). 

Note that I am not advocating that you have to use sections everywhere. I only want to discuss if we can agree on a best practice that if you mark sections, you use a particular, agreed-upon way to do that.

Other than that I fully agree with you that a preferred ordering is also a good idea. This is not something I want to over-regiment though: there are options in the code formatter to enforce a particular order, but I think we best leave this to developer discretion - you can of course choose to use auto-formatting in your own editor to re-order members, if you want.

It’s very helpful to when things are organized for very large files with many variables and many methods, but I’m not very great at keeping stuff organized like that myself. I find it great to read, but a pain to maintain because of all the manual work involved. 

A couple of observations:

1. I fully understand and also tend to be lazy about this myself.

2. However, I also realize that this is somewhat short-sighted: I have a responbility as a coder to make sure my code is easy to understand by others (including myself in six months time).

2. if a Java file is so large that this really becomes a massive chore, that's probably a sign that we should be refactoring and breaking up the "God class".

Perhaps this doesn't really need a fully agreed-upon best practice. I personally think that if some of us use

// Constructors

and others use:

/* Section: Constructors */

and still others generally don't bother marking out sections this way, we have still won in terms of clearer code. It's not an all-or-nothing thing.

Cheers,

Jeen

Håvard

On 7 Nov 2020, at 01:51, Jeen Broekstra <jeen@xxxxxxxxxxxx> wrote:



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

_______________________________________________

rdf4j-dev mailing list

rdf4j-dev@xxxxxxxxxxx

To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/rdf4j-dev

_______________________________________________

rdf4j-dev mailing list

rdf4j-dev@xxxxxxxxxxx

To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/rdf4j-dev