This poll evolved from this thread. It’s the first one in a series of polls, but we first we need to decide whether we want a consistent style or not. Based on the results, we can take it from there.
Question: Should tutorials on fortran-lang.org follow a consistent style for code listings?
0 voters
I voted yes, but with the condition that if we cannot find consensus, then I am voting no to having a style guide that would alienate prominent members of our community.
We have to understand that we must act as stewards of the language, and people active here (including myself) are not necessarily representative of the wider community of Fortran programmers. So in issues like this one, we have to try our best to ensure that any such style guide does not alienate people.
I suspect that we can find consensus on wide range of issues, and we should write those down. I also suspect there will be some issues like indentation where we might not be able to find consensus, but let’s at least document the several widely used options, and then we’ll decide what to do next.
I think there has to be uniformity for the tutorials. Without that, it will look unprofessional or haphazard (at best), and at worst will cause confusion among beginners.
But, I agree we shouldn’t be driving people away. If somebody wants to contribute content in a different style I’m all for it. Somebody can go in later and impose the standards (or maybe there’s even a way to automate it). But ultimately, I think it needs to all be in a consistent style.
This is a non-issue. Everything we’re building we do so under majority consensus. If a majority community decision would alienate a member, there’s a deeper issue with working with such member to begin with. By participating, we all agree that we will set our personal preferences aside when the majority of the community chooses otherwise.
For specific issues that are truly split without consensus, we can discuss how to proceed. One solution could be to make an exception for only that item, and allow both to be used.
The only such item that I recall was indentation width of 2 vs 4. And for that there’s a technical argument for 2 over 4 (fewer continued lines), and even more so for listings in tutorials, which must read well on mobile.
The problem with style guides is that they’re fine as long as it’s your style. You only have to look at the world of C++ and the positioning of brackets to see what a world of pain awaits. In the '90s we spent 3 days of company time trying to agree what the line continuation character should be, and how about ‘endif’ vs ‘end if’? And there is a real risk of alienating people who post code here and then have it criticised for not following the style guide.
I agree with Simon.
If a majority community decision would alienate a member, there’s a deeper issue with working with such member to begin with.
Milan, let’s be very careful here and precise.
As a community, it’s impossible to agree 100%. We ask each member to be reasonable. Say somebody like myself disagrees to use “fpm new” and would prefer “fpm init”. I am in the minority currently (at least it seems), so I give in. It’s just one command. I agree with most other design decisions and so this one issue just becomes minor in the grand scheme of things.
Coding style on the other hand is different. First of all, it is deeply personal. And it’s not just one thing, it’s every code all the time. And forcing a majority opinion on a minority can have very bad cumulative effects. Especially if we don’t know what the majority opinion is: we have say 20 votes. But the Fortran community is at least 100x or more bigger. So our vote is less than 1%. Each of us is sort of like a superdelegate. We each represent our colleagues who don’t vote here.
You can see already six people voted against.
For this reason I propose to try to constructively find consensus on at least a subset of the guidelines. And on things like indentation where we will not all agree, let’s at least summarize the main options out there in wide use. It will not be that many.
That would be a good start that doesn’t alienate anyone, and we can go from there. We don’t need to achieve one true style right away if it means alienating people. It’s not worth it.
I agree. I think this is also in line with Simon’s “The problem with style guides is that they’re fine as long as it’s your style”. This is not going to be easy nor perfect. But we can work together toward a solution.
I see from both your and Simon’s responses that you got caught on “Style guide” or “Coding style”.
Let me rephrase the question: Do you think tutorials should use a consistent or random style for code? (There are only two possible answers here.) (To prevent further confusion, I will rename the title of the poll).
The Style Guide discussed here would not force anybody to code in any specific style. Instead, it’s only meant to inform how should the tutorial listings be displayed on the website. It does not impact any other project.
Coding style on the other hand is different. First of all, it is deeply personal. And it’s not just one thing, it’s every code all the time.
Does my paragraph above address this concern in a satisfactory way? It’s just tutorials. You don’t have to code in a style you don’t like.
Even if you want to contribute a section and submit it in your own style, it’s fine. Reviewers can take care of it. I for one volunteer to help edit the submissions.
I think consistent style for a learning material is a must. No book would get past its editor or even the first peer review unless using a consistent style. We need to keep the standard high here.
And there is a real risk of alienating people who post code here and then have it criticised for not following the style guide.
@simong There is a risk that it would happen if indeed such criticism occurred. I agree it would be unacceptable. We have a code of conduct that we enforce to make sure that only respectful and constructive criticism is given. I promise to personally working toward this being a safe and inclusive environment for everybody.
By all means I am not saying that we shouldn’t care about minority that disagrees. I’m saying that I don’t think there will be major problem with this effort, and if a problem comes up, we can work together toward a solution.
A minimal style guide is definitely needed, should be enforced via CI and made available to submitters/developers with a pre-commit hook. In my experience many people oppose coding styles since it would mean changing their setup/habit. Automation often seems to help.
If the code snippets are separate files, fprettify can be used (there is also a pre-commit configuration already included).
Yes, I think this is all we need for now.
I am re-reading these messages now and realize that we are all here mostly in agreement. I as well don’t think we should enforce or put in place anything that would alienate members. But I didn’t write this explicitly and I thought I should.
A consistent style within a tutorial is a good idea, but I’m not convinced it is a good idea to require the same style for all tutorials - code clarity is much more important. But I’m happy to contribute to the debate to see where it goes.
Perhaps this is a bit off-topic but I would love to see a thread where people report their preferences in terms of coding style for some different categories.
I’m sure that in many cases preferences are just personal and not necessarily logical, perhaps because one got used to reading and write code in that specific way, while in other cases there may be some good justification for choosing some specific rules. Personally I would find it quite helpful as sometimes I find myself coding with a somewhat inconsistent style simply because I’m missing some rules for relatively specific cases. Something that would take less work would be to take a short program with some of the most used features of the language where people could re-write it in their own style (I think something like this has been discussed in some issue on GitHub). This may sound a bit vague, but for instance: I very often find myself coding in a way that, while the code reads well to me, I find it hard to describe the style with a set of rules, like for the alignment of the logical operations in the code snippet below (or the spacing encompassing the .or. operations):
passed_loc = .true.
do ivel = 1,3
do idir=1,3
bc01v = cbcvel(0,idir,ivel)//cbcvel(1,idir,ivel)
passed_loc = passed_loc.and.( (bc01v == 'PP').or. &
(bc01v == 'ND').or. &
(bc01v == 'DN').or. &
(bc01v == 'NN').or. &
(bc01v == 'DD') )
enddo
enddo
if(.not.passed_loc) call write_error('velocity BCs not valid.')
passed = passed.and.passed_loc
I think that such an exercise would help some of us to reflect about rules and become more structured; it would definitely help me!
What I personally, have in mind about the style, is something very basic, along the lines of how they did it in Rust, check at main site: Learn -> Rust by example. From a quick look, I could only find four common styles that all code snippets follow, in order to be consistent.
name{
}
instead of
name
{}
// instead of /* */.Regarding Fortran, we could debate for the 2. and 4. and perhaps for "endif, enddo" vs "end if, end do". My point is to focus only on a few basic styles that are the most commonly met in tutorial snippets, without worrying about details.
Should tutorials on fortran-lang.org follow a consistent style for code listings?
I think they should.
Will tutorials on fortran-lang.org follow a consistent style for code listings?
That is the question…
A Style Guide on key points is surely better than none, keeping in mind that a guide is not a rule, and anyway rules are made to be broken… (but with a good reason).
That’s what we’ve been doing with stdlib and its style guide here. I don’t think all contributions followed it to a letter and it has been working.
I think consistency is more important for teaching material, but again, this could be taken care of at a copy-editing or type-setting stage, just like with any other book. Writers could write in their favorite style and reviewers/editors could make sure it’s consistent with the rest of the mini-book. Styles could vary between mini-books as Simon pointed out.
@milancurcic, to move the conversation further, do you want to setup some repository / document and as @everythingfunctional suggested, take some code example and format it in different styles that people prefer? Let’s ensure all of us can find our favorite style represented there. That would be a huge step forward. I think we can agree on more things than we disagree. On the things we disagree, my suggestion is to not press the issue yet, but document the different approaches.
Perhaps the style will be something like:
end if
As long as 99% of the community is represented in this style guide, then I would say this is a huge win.
I know some of you say, but we need to choose exactly the amount of spaces and just one indentation scheme, otherwise it will not look professional. I am not sure. But either way, having the above style guide that allows options is a huge step forward, that we can build upon later to perhaps restrict some of the options, if the community would prefer that, but let’s have that conversation about what to restrict later. Right now let’s document what the options are. I think we will be all surprised that there are not that many options in wide use, and this would provide an excellent foundation for future discussion. This is a tough problem that we will not solve immediately, and so let’s just move towards solving it eventually by doing the first step now, and understand that this is the first step of many, not the last step.
So that would be my recommendation.
Excellent! I will.
I also think that we will agree on most items, and for those that we don’t we can use both preferences.