Poll: Preferred style for tutorial code listings

This is the first basic poll for the style of the tutorial code listings. It only covers a few items: Variable and procedure naming style, indentation width, and whether to use a space in various end statements. They’re quite fundamental and appear in almost any code. The last one I included because a few people expressed that it may be controversial, so it’s useful to get a community pulse on it.

Once we have the results we can write up a basic style guide. Other elements of style we can tackle if the need arises.

Please read the examples below and cast your vote in each of the 4 polls.

Variable naming

What style should we use for naming variables? Examples:

integer :: GRIDSIZE  ! UPPERCASE
integer :: gridsize  ! lowercase
integer :: grid_size ! snake_case
integer :: gridSize  ! camelCase
integer :: GridSize  ! PascalCase

Vote below (multiple choice answers):

  • UPPERCASE
  • lowercase
  • snake_case
  • camelCase
  • PascalCase

0 voters


Procedure naming

How about for procedures? Examples:

function ROOTMEANSQUARE(x)
  ...

function rootmeansquare(x)
  ...

function root_mean_square(x)
  ...

function rootMeanSquare(x)
  ...

function RootMeanSquare(x)
  ...

Vote below (multiple choice answers):

  • UPPERCASE
  • lowercase
  • snake_case
  • camelCase
  • PascalCase

0 voters


Indentation

How many spaces to use when indenting code? Examples:

do i = 1, 5
 print *, i ! 1-space indent
end do

do i = 1, 5
  print *, i ! 2-space indent
end do

do i = 1, 5
   print *, i ! 3-space indent
end do

do i = 1, 5
    print *, i ! 4-space indent
end do

Vote below (multiple choice answers):

  • 1
  • 2
  • 3
  • 4

0 voters


How to write various end statements?

Various Fortran constructs such as do-loops and if-blocks are closed with their corresponding end statement. For example

do i = 1, 5
  print *, i
end do

which can also be written as:

do i = 1, 5
  print *, i
enddo

The question is should such end statements be written together (enddo, endif, endwhere, etc.) or separate (end do, end if, end where, etc.).

Cast your vote below:

  • Without space (enddo, endif, endwhere, etc.)
  • With space (end do, end if, end where, etc.)

0 voters

Is there some reason why the last poll (“end do” vs “enddo” etc) does not allow accepting both options, in contrast to other polls that allow selecting multiple options at once? (In my case, I would select both or a “whichever” button, if available.)

And, another poll might be “whether ‘end subroutine subroutine-name’ should be used even for short subroutines?”. Many people tend to do so even for very short subroutines, possibly by learning from books and tutorial sites. But I feel it not useful for short subroutines because it makes the code simply more verbose and noisy (the same applies to “end type type-name” for small things etc), and might make the impression that people should always follow it as “good practice” (which I am afraid of, but this is just my opinion…)

2 Likes

I think this poll might be about what you personally prefer. I think Milan probably assumed that you only like one option.

1 Like

Sorry! Indeed I had assumed only one option for the last poll, but I realize that could also accept both choices, meaning, you like it either way. Unfortunately, I can only edit a poll in the first 5 minutes. If you prefer both choices for the last poll, just write it in the thread. First 3 polls already accept multiple choices.

@certik, Hi thanks for your comment, and I’ve just updated my post for more clarity (I felt it is somewhat strange that only the last poll does not have “up to … options”, though it might be natural if the number of options is just two).

@milancurcic I see… I was afraid that a similar “war” between “enddo” and “end do” could happen, which is meaningless, IMHO.) And thanks very much anyway for making these threads :slight_smile:

A quick comment about indentation that may be helpful. At the time I write it is evenly split between 2 and 4 spaces. I greatly prefer 2 spaces (and voted such) for real code, because I feel 4 spaces consume way too much usable line space. However I think tutorials are bound to be relatively simple code, and as such 4 spaces may give better clarity without sacrificing much in this context. Perhaps I should go back and change my vote …

4 Likes

Yes, I thought of this one as well but decided to save it for the next or future poll, as this one was getting busy already.

1 Like

@nncarlson I also indent with 2 spaces in my own code for the same reason as you. For tutorials, I like 2 and 4 equally well and I don’t find 4 any less readable. If I’m reading somebody’s code or a tutorial, I don’t mind any level of indentation as long as it’s consistent. However, I did vote for 2 only in this poll because I’m concerned about the tutorials on mobile.

For example, on my phone (Moto G7) in Chrome, I get 37 characters before the code wraps around in a new line. Even with simple examples in the current tutorials, many lines of code wrap around.

3 Likes

Ah, I hadn’t considered mobile at all; space is indeed a premium there.

It will be awesome if a team can work toward some ‘beautify’ script or a tool that can take Fortran snippets, examples, tutorials submitted by contributors and transform the code into the agreed-upon style specification .

Readers here will have noticed facilities like this already exist in certain editors and IDEs, particularly with indentation where the editor/IDE can ‘format indent’ a selection or a document to desired style such as with 2 or 3 or 4 spaces as requested by the user.

Now, with Fortran given its legacy since the IBM mainframe days, there is also the question of whether the tokens recognized by the language (‘program’, ‘integer’, ‘print’, ‘end’, and on and on) should be uppercase or lowercase or some other mixed case style. Should a contributor prefer uppercase for language tokens (note I’ve come across quite a few long-time Fortranners who insist on this) but if this site were to settle on another, the tutorial ‘editor’ at this site can quickly transform the submitted code with a code formatter for a consistent style.

2 Likes

@FortranFan https://github.com/pseewald/fprettify … tested on 1M+ LOC.
But enddo -> end do as well as shouldBeSnakeCase to should_be_snake_case are not yet implemented afaik.

I would like to suggest there be a distinction made between variables and constants. Or at least discuss whether there should be a distinction. i.e.

integer, parameter :: GRID_SIZE = 10
4 Likes

Yes, I had assumed it distinct (thus, “variable” in the poll). This could be a separate poll item.

It looks like on most polls except “indentation” there is a clear majority opinion. However, even in those, there is a significant minority opposition, so I would formulate the conclusion / guideline as something like:


For tutorials:

  • use “end if”

As that is what most people seem to prefer. However, in your own projects you are welcome to use any formatting you see fit. We will eventually have a tool similar to clang-format which will allow to configure the default formatting for each project according to their preferences.


For “indentation”, the opinions seem to be completely split: 38.5% for 4 spaces, 38.5% for 2 spaces, 19.2% for 3 spaces and 3.8% for 1 space. That exactly mirrors my experience with this question, people truly prefer various ways, and there is no clear winner. So I would strongly suggest to respect that and simply say, use 4, 2 or 3 spaces, but please be consistent within the page.

If later we run this poll again and there is more consensus, we can always reformat all the code. That way we have some guidelines to start with, and we can restrict them more later.

3 Likes

That’s my conclusion as well and I think a good way forward.

1 Like

Right, consistency is key. Here we’re basically starting from scratch so it’s worthwhile finding some common denominators.

1 Like

Indeed, I also prefer 3 spaces which (I feel) can highlight a code block reasonably well, while not making a line too long for nested blocks. I used to use it with the “f77 mode” in Emacs, but from around 2000-2010, the “default” mode of various editors moved to 4 spaces (partly due to python/pep8?) or 2 spaces. So I was a bit surprised that some people like 3 spaces in the above poll.

My another question is whether people feel uneasy (?) for odd numbers. I wonder if there is some psychological reason why people prefer 2 or 4 over 3. (<-- here I’m not recommending 3 for the above tutorial, but just wondering about various languages/editors etc).

2 Likes