Poll: Preferred style for tutorial code listings

[milancurcic]

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

---

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

---

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

---

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.)

[septc]

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…)

[certik]

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

[milancurcic]

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.

[septc]

@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

[nncarlson]

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 …

[milancurcic]

@septc

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…)

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.

[milancurcic]

@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.

[nncarlson]

@milancurcic

I’m concerned about the tutorials on mobile

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

[FortranFan]

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.

[tiziano.mueller]

@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.

[everythingfunctional]

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

[milancurcic]

@everythingfunctional

I would like to suggest there be a distinction made between variables and constants.

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

[certik]

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.

[milancurcic]

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

[milancurcic]

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

[septc]

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).

[RonShepard]

I like indenting 3 spaces because it goes well with with IF and DO. 1 or 2 spaces sometimes requires me to lay a ruler on my screen (or printout) to see if separate blocks are really aligned with each other or not. 4 spaces is alright, but when you have deep nesting, there seems to be too much wasted screen space. Also with fixed-form fortran, 4 spaces would often get to too close to the right edge, column 72. So 3 seems like the optimal compromise.

I prefer all upper case for macros (cpp style), and some kind of mixed upper and lower case for fortran variables and parameters. This avoids the potential problem when a cpp macro just happens to be the same as a variable name. This is one of the issues with using cpp for fortran codes, and why fortran should have had its own preprocessor decades ago. However, I also sometimes use single-character uppercase for matrices A(:,:) and single-character lowercase x(:) for vectors, the common convention in mathematics.

My eyesight is not as sharp as it used to be, so I find myself using more horizontal spacing that I used to. Now I often put spaces around operators, after commas, and so on.

A problem with camelCase and PascalCase variable names is that when you modify the code, it takes extra effort to be consistent. The case doesn’t matter in fortran (unlike C, for example), so the compiler doesn’t tell you when you made a mistake. Then a subsequent programmer sees the variable MyA, myA, and Mya and is confused.

I always type enddo and endif together. Why waste time putting in that space? That is time wasted in your life that you will never get back. But I do put the space in end subroutine, end function, end type, end module and other places like that. Those would look confusing without the space.

For function and subroutine names, it is sometimes confusing to see an unresolved symbol error “mysub” when what is typed in the code is MySub. You do a search and don’t find the problem, until you remember to do the search and ignore case, and then you find it.

[Jcollins]

For spacing in end statements our own standard uses ENDDO, ENDIF and ENDWHERE, but END PROGRAM, END MODULE, END FUNCTION, END SUBROUTINE, END BLOCK, END ASSOCIATE, END TYPE. There are also END STRUCTURE, END UNION, END MAP, END BLOCK DATA if anyone cares. I accept that this is inconsistent. What are the feelings of other users?