ESTEL:ESTEL-3D code formatting guidelines

This is a try at setting up some guidelines to make developing ESTEL-3D easier. They are not definitive rules and they are many places in the code where these rules are not followed. It will take time...

= Very important rules =

! A long comment that requires a lot of room so it is easier to use all the ! room we can that means up to the 72nd character. Indent as required. integer :: variable_with_long_comment
 * Comment your code!!! A lot. In English. And in a way that is understandable to those who have not written the code. there are many way to comment the code, if done well, it should not take too long and it will certainly be appreciated by other.

character(len=12) :: variable_with_short_comment ! Short comment


 * Use sane variable names. If you describe a counter call it  rather than  . The exception could be ,   and   to use in loops. Note that   for nodes,   for boundary nodes or   for elements is are good choices too. If you name your variables well, it will be simpler to comment your code.


 * Keep to the 72 character line limit of Fortran77 but use the other rules of Fortran90 free form. This is because some compilers seem to still have problem with longer lines. All horizontal lines in the templates are 72 characters long.


 * Do not use tabulation marks in the files to show indentation. Tabulations (tabs) are not part of Fortran90. Configure your text editor to automatically convert them to spaces.


 * Do not use " " statements inside subroutines, they should be in the module header.


 * Every subroutine should use " ". All of them!


 * Use " " for all arguments. All of them!

= Important rules = Because we now use subversion to store the sources of ESTEL-3D some information becomes unnecessary inside a source file:
 * there is no need to write dates in the files. Ideally, the only date should be a lost of years at the top of each file for the EDF copyright statement.
 * try to avoid writing names and email addresses in the files unless really necessary.
 * there is no need to write version numbers in the files.

The above rules are there for a reason: this type of information will be obsolete very soon.

Furthermore, it is very easy to find:
 * the author of a particular line in the file foo.f90, use
 * the history (as in dates, revision numbers, authors, comments) for the file foo.f90, use

= Guidelines regarding formatting = As other people will read your code, please try to also do the following:

! Example of indentation with two spaces do   do      if  then call foo else call bar endif enddo enddo
 * Use indentation but not too much. As we want to stick to 72 characters, using many spaces to indent will force to continue on a new line. Use 2 spaces to indent, it is enough to separate blocks:


 * Do not type your code in capital letters only (Only Fortran programmers do that for some reason that nobody can explain...) Lower case letters exist, they are fine too, they are also easier to read (especially for comments) so use lower case letters too.

! thing comes from ESTEL-3D ! CHOSE comes from BIEF thing = 2* CHOSE
 * Try to separate BIEF from ESTEL-3D in terms of variable or subroutine names or mention explicitly when you are using something that is from BIEF. One solution is to use capital letters only for BIEF and mixed caps/lowercase for ESTEL-3D, e.g.:

call SUB(thing,CHOSE) ! SUB is a BIEF subroutine

integer, intent(in)          :: var1 ! This integer only comes in integer, intent (inout)      :: var2 ! This one comes in an out double precision, intent(out) :: var3 ! this real only goes out
 * Try to align code and comments when there are obvious blocks so that it is easier to read them, for instance:

sub1( arg1,      &      arg2,       &      long_arg_3, &      arg4 )
 * Align arguments and continuation markers if possible: