Fortran - Code as documentation

Author

Code as documentation

David Flower

2008-01-23, 8:21 am

In another thread, I suggested that programmers should avoid using
defaults when the same thing can be specified explicitly.

It seems to me that posters could create a list of such situations, so
here's a few to start off with.

1) Explicitly SAVE all variables that need to be saved, and no others.

2) Avoid using then left-to-right rule in the avaluation of
expressions (e.g. X/Y*Z)

3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)

Let's have some comments and other examples

Dave Flower

Ian Bush

2008-01-23, 8:21 am

As if by magic, David Flower appeared !

> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)
>
> 3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)
>

4) Type all variables

5) Where possible use Intent

Ian

Paul van Delst

2008-01-23, 8:21 am

David Flower wrote:
> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)

So ... X/Y*Z is looked upon with disfavour?

What about Z*X/Y? I evaluate that left-to-right too.

I think you may need to explicitly mention the word "parentheses" or "brackets" somewhere
in your spec. :o)

> 3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)
>
> Let's have some comments and other examples
>
> Dave Flower

Paul van Delst

2008-01-23, 8:21 am

Ian Bush wrote:
> As if by magic, David Flower appeared !
>
>
> 4) Type all variables

Or: Always use IMPLICIT NONE.

>
> 5) Where possible use Intent

...to do...? What? For a set of rules to help code be more explicit, they sure aren't.

:o)

cheers,

paulv

p.s. Apologies. Late night, no coffee yet......

Gordon Sande

2008-01-23, 7:19 pm

On 2008-01-23 10:06:39 -0400, Paul van Delst <Paul.vanDelst@noaa.gov> said:

> David Flower wrote:
>
> So ... X/Y*Z is looked upon with disfavour?

Isn't the problem that the two operators / and ** do not have universal
instant association rules. They should be made redundently clear by use
of adequate parentheses. Just a special case of if the default is
unclear to "non experts" then make it explicit. Remenber the code will
be read by some idiot. Typically the programmer about twenty minutes
in the future!
[color=darkred]
> What about Z*X/Y? I evaluate that left-to-right too.
>
> I think you may need to explicitly mention the word "parentheses" or
> "brackets" somewhere in your spec. :o)
>
>

Beliavsky

2008-01-23, 7:19 pm

On Jan 23, 9:09=A0am, Paul van Delst <Paul.vanDe...@noaa.gov> wrote:
> Ian Bush wrote:

<snip>

>
> ..to do...? What? For a set of rules to help code be more explicit, they s=
ure aren't.
>
> :o)

Use the most restrictive INTENT possible. Don't write INTENT (IN OUT)
if INTENT(IN) or INTENT(OUT) will suffice.

mecej4

2008-01-23, 7:19 pm

Paul van Delst wrote:
> David Flower wrote:
>
> So ... X/Y*Z is looked upon with disfavour?
>
This case is confusing because the Fortran meaning differs from that in
a mathematical text. In algebra, the convention is that a/bc means
<Fortran> a/(b*c) </Fortran>, as opposed to <Fortran> a*c/b) </Fortran>

> What about Z*X/Y? I evaluate that left-to-right too.

This case has no ambiguity
>
> I think you may need to explicitly mention the word "parentheses" or
> "brackets" somewhere in your spec. :o)
>
Yes.
[color=darkred]

-- mecej4

James Giles

2008-01-23, 7:19 pm

David Flower wrote:
....
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)

In a similar vein, Dijkstra recommended that AND and OR
operations be the same precedence and not associate with
each other. (He spelled these /\ and \/ respectively, only he
used single characters with approximately that appearance).
So the followin would be legal:

A /\ B /\ C
X \/ Y \/ Z

But the compiler would flag the following as errors:

A /\ J \/ Z
B \/ J /\ Z

In these latter two you would be required to parenthesize to
clarify which was to be done first.

Also recommended was to use more space to delimit lower
precedence operators and less to delimit higher precedence
operators when parenthesis aren't used:

A + B*C <= P .and. X**I + Y > 5.0

Of course, this can be abused by deliberately doing it the other
way around:

A + B * C<=P.and.X ** I + Y>5.0

Though that looks not so much confusing as just ugly.

Using both parenthesis and whitespace can improve things even more.

--
J. Giles

"I conclude that there are two ways of constructing a software
design: One way is to make it so simple that there are obviously
no deficiencies and the other way is to make it so complicated
that there are no obvious deficiencies." -- C. A. R. Hoare

glen herrmannsfeldt

2008-01-23, 7:19 pm

mecej4 wrote:
> Paul van Delst wrote:
(snip)

[color=darkred]
> This case is confusing because the Fortran meaning differs from that in
> a mathematical text. In algebra, the convention is that a/bc means
> <Fortran> a/(b*c) </Fortran>, as opposed to <Fortran> a*c/b) </Fortran>

As far as I know, a/bc in algebra means (a/b)*c, but in a
book you can write:

a
-----
b c

which means a/(b*c). You can't do that in Fortran.

I am not so sure that the current algebraic precedence wasn't
borrowed back from Fortran, though.

-- glen

garylscott@sbcglobal.net

2008-01-23, 7:19 pm

On Jan 23, 2:49=A0pm, glen herrmannsfeldt <g...@ugcs.caltech.edu> wrote:
> mecej4 wrote:
>
> (snip)
>
>
> As far as I know, a/bc in algebra means (a/b)*c, but in a
> book you can write:
>
> =A0 =A0a
> -----
> =A0 b c
>
> which means a/(b*c). =A0You can't do that in Fortran.
>
> I am not so sure that the current algebraic precedence wasn't
> borrowed back from Fortran, though.
>
> -- glen

http://en.wikipedia.org/wiki/Order_of_operations

I say we just follow this as closely as possible where possible and
where not, define explicitly the rule and reason for the exception.

Gordon Sande

2008-01-23, 7:19 pm

On 2008-01-23 16:49:59 -0400, glen herrmannsfeldt <gah@ugcs.caltech.edu> said:

> mecej4 wrote:
> (snip)
>
>
>
> As far as I know, a/bc in algebra means (a/b)*c, but in a
> book you can write:
>
> a
> -----
> b c
>
> which means a/(b*c). You can't do that in Fortran.
>
> I am not so sure that the current algebraic precedence wasn't
> borrowed back from Fortran, though.
>
> -- glen

I would have thought that in a purely multiplicative expression
in "prose algebra" the division sign separated the numerator from
the denominator and implied grouping of both the numerator and
denominator. Thus "a b / c d" was short for "( a b ) / ( c d )".
All of which is why the grouping needs to be explicit as the
computer did not go to the same elementary algebra classes as I did.

Notation is always a bit squirrely. Thee are even some fields (in
algebra and functional analysis) that have unique notations for
some of their operations.

And then there are the folks who use <x| and |y> (bras and kets)
for inner products. To say nothing of the folks who rely on the
summation convention to imply summation.

James Giles

2008-01-23, 7:19 pm

glen herrmannsfeldt wrote:
> mecej4 wrote:
> (snip)
>
>
>
> As far as I know, a/bc in algebra means (a/b)*c, but in a
> book you can write:
>
> a
> -----
> b c
>
> which means a/(b*c). You can't do that in Fortran.
>
> I am not so sure that the current algebraic precedence wasn't
> borrowed back from Fortran, though.

In fact I have several math books older than Fortran and I can't,
on quick perusal, even find forms like a/bc in them. They always
write the horizontal line with 'a' on top and 'bc' on the bottom.
It's doubtful that such a form was even used, much less that it
had a specific meaning. Now, they do often use things like x/y,
with only one thing top and bottom. I can't even find instances
of things like ab/c. The only common multiletter form is dy/dx,
but there the numerator and denominator are still single entities.

The / operator probably shouldn't associate. That is, all uses of
it where either operand is an expression with another operator of
the same precedence should probably be required to be parenthesized
to clarify meaning:

a/(b*c) or (a/b)*c and not a/b*c
(a/b)/c or a/(b/c) and not a/b/c
(a*b)/c or a*(b/c) and not a*b/c

You could have Fortran generate a warning message of any of the
non-parenthetical forms above are used. It can't be a fatal error
because of backward compatibility.

The same argument might be applied to subtract (-), except there
*is* an existing mathematical interpretation for that.

--
J. Giles

"I conclude that there are two ways of constructing a software
design: One way is to make it so simple that there are obviously
no deficiencies and the other way is to make it so complicated
that there are no obvious deficiencies." -- C. A. R. Hoare

john.harper@vuw.ac.nz

2008-01-23, 7:19 pm

On Jan 24, 1:18 am, David Flower <DavJFlo...@aol.com> wrote:
> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)
>
> 3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)
>
> Let's have some comments and other examples
>
> Dave Flower

4) Give the length of character variables and constants even when
it's
1, e.g. CHARACTER,PARAMETER::back*1='\' ; CHARACTER(1) a,b

5) Use the optional KIND argument of the CMPLX and REAL intrinsics.

-- John Harper, School of Mathematics, Statistics and Computer
Science,
Victoria University, PO Box 600, Wellington 6140, New Zealand
e-mail john.harper@vuw.ac.nz phone (+64)(4)463 5662 fax (+64)(4)463
5045

Louis Krupp

2008-01-23, 7:19 pm

James Giles wrote:
<snip>

> The / operator probably shouldn't associate. That is, all uses of
> it where either operand is an expression with another operator of
> the same precedence should probably be required to be parenthesized
> to clarify meaning:
>
<snip>
> (a*b)/c or a*(b/c) and not a*b/c

Unless I'm mistaken, this one is not ambiguous; the meaning is the same
either way.

Louis

Craig Dedo

2008-01-23, 7:19 pm

"Gordon Sande" <g.sande@worldnet.att.net> wrote in message
news:2008012310331916807-gsande@worldnetattnet...
> On 2008-01-23 10:06:39 -0400, Paul van Delst <Paul.vanDelst@noaa.gov> said:
>
>
> Isn't the problem that the two operators / and ** do not have universal
> instant association rules. They should be made redundently clear by use
> of adequate parentheses. Just a special case of if the default is
> unclear to "non experts" then make it explicit. Remenber the code will
> be read by some idiot. Typically the programmer about twenty minutes
> in the future!

Generally, in math or other fields of study, the associativity rules for /
and ** may not be universal. However, Fortran has explicit, well-defined
associativity rules for both. In section 7.1.1.3 of the Fortran 2003 standard,
syntax rules R704, R705, R707, and R708 define the associativity for **, *, and
/. Note 7.31 in section 7.3 clarifies these syntax rules and provides some
examples. Here is an excerpt from that note:
[Begin excerpt]
For example, the expressions
:
2.1 / 3.4 / 4.9
2 ** 3 ** 4
have the same interpretations as the expressions
:
(2.1 / 3.4) / 4.9
2 ** (3 ** 4)
[End of excerpt]

--
Craig Dedo
17130 W. Burleigh Place
P. O. Box 423
Brookfield, WI 53008-0423
Voice: (262) 783-5869
Fax: (262) 783-5928
Mobile: (414) 412-5869
E-mail: <cdedo@wi.rr.com> or <craig@ctdedo.com>

Richard Maine

2008-01-23, 7:19 pm

Louis Krupp <lkrupp@pssw.nospam.com.invalid> wrote:

> James Giles wrote:
> <snip>
>
> <snip>
>
> Unless I'm mistaken, this one is not ambiguous; the meaning is the same
> either way.

Algebraically, yes. Computationally, not necessarily. For example, one
could overflow or underflow while the other foesn't.

--
Richard Maine | Good judgement comes from experience;
email: last name at domain . net | experience comes from bad judgement.
domain: summertriangle | -- Mark Twain

Louis Krupp

2008-01-23, 7:19 pm

Richard Maine wrote:
> Louis Krupp <lkrupp@pssw.nospam.com.invalid> wrote:
>
>
> Algebraically, yes. Computationally, not necessarily. For example, one
> could overflow or underflow while the other doesn't.
>

This is also true even if only one operation is involved; (a+b)+c might
not turn out the same as a+(b+c).

Louis

Richard Maine

2008-01-23, 7:19 pm

David Flower <DavJFlower@aol.com> wrote:

> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
....
> Let's have some comments and other examples

Explicitly say what it is that you are ending with an END statement.
(I'm particularly sensitive to this because I recall Pascal compilers
interpreting what I intended to be the end of some block as being the
end of the whole procedure, or vise versa). Thus

end subroutine whatever

instead of just

end

For DO loops and IF blocks, the language requires at least END DO or END
IF, but make it more explicit by using construct names so that it is
something like

end do read_loop

rather than forcing the reader to figure out which level of possibly
nested DOs this particular END goes with, particularly if the start of
the loop is back a page (or screen or whatever) or so.

Exceptions allowed when the construct is short enough for the connection
to be obvious. But if nexting is involved, even very short ones can
become non-obvious, so make them explicit.

I'm aware that some people don't go as far as I do in this direction,
but that's my personal style rule, and it seems to fit in your category
of making things explicit.

--
Richard Maine | Good judgement comes from experience;
email: last name at domain . net | experience comes from bad judgement.
domain: summertriangle | -- Mark Twain

James Giles

2008-01-23, 7:19 pm

Louis Krupp wrote:
> James Giles wrote:
> <snip>
>
> <snip>
>
> Unless I'm mistaken, this one is not ambiguous; the meaning is the
> same either way.

Only under the assumption that computer arithmetic is mathematically
exact. Of course, Fortran permits "mathematically equivalent" re-
arrangements provided the integrity of parentheses are preserved.
Probably all the more reason to always use parentheses.

--
J. Giles

"I conclude that there are two ways of constructing a software
design: One way is to make it so simple that there are obviously
no deficiencies and the other way is to make it so complicated
that there are no obvious deficiencies." -- C. A. R. Hoare

Gordon Sande

2008-01-23, 7:19 pm

On 2008-01-23 18:05:16 -0400, "Craig Dedo" <cdedo@wi.rr.com> said:

> "Gordon Sande" <g.sande@worldnet.att.net> wrote in message
> news:2008012310331916807-gsande@worldnetattnet...
>
> Generally, in math or other fields of study, the associativity
> rules for / and ** may not be universal. However, Fortran has
> explicit, well-defined associativity rules for both. In section
> 7.1.1.3 of the Fortran 2003 standard, syntax rules R704, R705, R707,
> and R708 define the associativity for **, *, and /. Note 7.31 in
> section 7.3 clarifies these syntax rules and provides some examples.
> Here is an excerpt from that note:
> [Begin excerpt]
> For example, the expressions
> :
> 2.1 / 3.4 / 4.9
> 2 ** 3 ** 4
> have the same interpretations as the expressions
> :
> (2.1 / 3.4) / 4.9
> 2 ** (3 ** 4)
> [End of excerpt]

It is not useful if the precisely defined result is so obscur that the
user does not realize that what was writen and what was intended are
quite different. Sort of the opposite of what you see is what you get.
The problem is not ambiguity in the formal language definition but
in the difference from the informal common expectation.

The truely perverse situation would be if someone corrected a technically
correct but perceptually wrong form into the one which was perceived to
be correct but was technically wrong. The solution is the suggestion
that arises often in such discussions of providing warning diagnostics
for these high confusion forms.

Not hard to do but rarely if ever done as it is merely useful!

James Giles

2008-01-23, 7:19 pm

Gordon Sande wrote:
> On 2008-01-23 18:05:16 -0400, "Craig Dedo" <cdedo@wi.rr.com> said:
....
>
> It is not useful if the precisely defined result is so obscur that the
> user does not realize that what was writen and what was intended are
> quite different. Sort of the opposite of what you see is what you get.
> The problem is not ambiguity in the formal language definition but
> in the difference from the informal common expectation.

In the above, the rule for exponentiation is (or ought to be) the common
expectation of programmers. The other possible interpretation is
mathematically the same as 2**(3*4) == (2**3)**4. And if you
wanted that you would presumably have used multiply on the
exponents to start with. Still, you make a good point. A single
universal rule is superior to inconsistent rules (plural) no matter
how much sense they may make individually. So perhaps exponentiation
should not associate at all. Then you could keep the single rule that
associative operators bind left to right.

> The truely perverse situation would be if someone corrected a
> technically correct but perceptually wrong form into the one which
> was perceived to be correct but was technically wrong. The solution
> is the suggestion that arises often in such discussions of providing
> warning diagnostics for these high confusion forms.

I agree. There are a large number of things that I think implementations
should warn about. Aside from the ones we've discussed already in
this thread, the list might include the following.

If the operand of a unary negation is the result of an exponentiation
operator (without parentheses), you should get a warning: -X**I
means -(X**I) by default and by the preexisting mathematical rules.
But is it what the programmer intends?

If a KINDless literal is used mixed mode with a non-default KIND
operand, you should get a warning: X = 0.1 most likely doesn't
get interpreted as expected if X is double precision.

Related to another current thread, if a dummy argument has the
TARGET attribute but the associated actual argument does not
you should get a warning. There are places where it might be
just fine. Usually not though.

And so on. There are half a dozen places where KINDless literals
should cause warnings. And these barely scratch the surface.

--
J. Giles

"I conclude that there are two ways of constructing a software
design: One way is to make it so simple that there are obviously
no deficiencies and the other way is to make it so complicated
that there are no obvious deficiencies." -- C. A. R. Hoare

Sebastian Hanigk

2008-01-24, 4:34 am

nospam@see.signature (Richard Maine) writes:

> For DO loops and IF blocks, the language requires at least END DO or END
> IF, but make it more explicit by using construct names so that it is
> something like
>
> end do read_loop
>
> [...]
>
> I'm aware that some people don't go as far as I do in this direction,
> but that's my personal style rule, and it seems to fit in your category
> of making things explicit.

Fortunately the F90 mode of Emacs does END-completion automatically :-)

Sebastian

Dieter Britz

2008-01-24, 8:20 am

glen herrmannsfeldt wrote:

> mecej4 wrote:
> (snip)
>
>
>
> As far as I know, a/bc in algebra means (a/b)*c, but in a

When, in a scientific text, you see, e.g. "1/2\pi", (writing "\pi" for
the symbol pi), you know that "1 over 2 pi" is meant. I am sure I have
seen this quite often, and in fact have to remind students to write
it differently in Fortran.
--
Dieter Britz (britz<at>chem.au.dk)

David Flower

2008-01-24, 8:20 am

On Jan 23, 12:18=EF=BF=BDpm, David Flower <DavJFlo...@aol.com> wrote:
> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)
>
> 3) Explicitly declare all relevant file specifiers (DISP=3D,FORM=3D etc.)
>
> Let's have some comments and other examples
>
> Dave Flower

Well, I seem to have stirred up quite an interesting discussion. A
couple of points:

Over/under flow accepted, X*Y/Z in unambiguous; however, suppose X, Y
and Z are INTEGERs ?

Backward compatibility requires that X/Y*Z be legal; however, this
does not prevent a compiler option to warn about any such constructs

Dave Flower

mecej4

2008-01-24, 8:20 am

David Flower wrote:
> On Jan 23, 12:18ï¿½pm, David Flower <DavJFlo...@aol.com> wrote:
>
> Well, I seem to have stirred up quite an interesting discussion. A
> couple of points:
>
> Over/under flow accepted, X*Y/Z in unambiguous; however, suppose X, Y
^excepted^ (?)
> and Z are INTEGERs ?

The CDC6400/6500/6600 Fortran manual (1969) covers this as follows:

"For example, 4*3/2 = 6 but 3/2*4 = 4"

>
> Backward compatibility requires that X/Y*Z be legal; however, this
> does not prevent a compiler option to warn about any such constructs
>
> Dave Flower

-- mecej4

Gary Scott

2008-01-24, 8:20 am

mecej4 wrote:
> David Flower wrote:
>
>
> ^excepted^ (?)
>
>
>
> The CDC6400/6500/6600 Fortran manual (1969) covers this as follows:
>
> "For example, 4*3/2 = 6 but 3/2*4 = 4"

Exactly as expected.

>
>
>
> -- mecej4

--

Gary Scott
mailto:garylscott@sbcglobal dot net

Fortran Library: http://www.fortranlib.com

Support the Original G95 Project: http://www.g95.org
-OR-
Support the GNU GFortran Project: http://gcc.gnu.org/fortran/index.html

If you want to do the impossible, don't hire an expert because he knows
it can't be done.

-- Henry Ford

mecej4

2008-01-24, 8:20 am

Gordon Sande wrote:
> On 2008-01-23 16:49:59 -0400, glen herrmannsfeldt <gah@ugcs.caltech.edu>
> said:
>
>
> I would have thought that in a purely multiplicative expression
> in "prose algebra" the division sign separated the numerator from
> the denominator and implied grouping of both the numerator and
> denominator. Thus "a b / c d" was short for "( a b ) / ( c d )".
> All of which is why the grouping needs to be explicit as the
> computer did not go to the same elementary algebra classes as I did.

Nor did many recent high-school graduates, as the following explanation
of function notation ( considering f(x) = x^2 ) hints:

> The f is not multiplying the x either, the f and the x are totally different kinds of creatures. The f is sort like a coke machine and the x is the 60¢--or whatever it's gone up to nowadays--and the x^2 is the can of coke.

-- taken from http://www.helpalgebra.com/articles...ionnotation.htm

One is left wondering what square cents signify.

> Notation is always a bit squirrely. Thee are even some fields (in
> algebra and functional analysis) that have unique notations for
> some of their operations.
>
> And then there are the folks who use <x| and |y> (bras and kets)
> for inner products. To say nothing of the folks who rely on the
> summation convention to imply summation.
>
>

Mirko.Vukovic@gmail.com

2008-01-24, 7:24 pm

On Jan 24, 3:33 am, Sebastian Hanigk <han...@in.tum.de> wrote:
> nos...@see.signature (Richard Maine) writes:
>
>
>
>
> Fortunately the F90 mode of Emacs does END-completion automatically :-)
>
> Sebastian

Also check out emacs' else mode (an implementation of DEC's wonderful
LSE editor). It does that as you type in the label.

Mirko.Vukovic@gmail.com

2008-01-24, 7:24 pm

On Jan 23, 7:18 am, David Flower <DavJFlo...@aol.com> wrote:
> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)
>
> 3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)
>
> Let's have some comments and other examples
>
> Dave Flower

Use doxygen with imbedded LaTeX equations to pretty print code.

Mirko

Sebastian Hanigk

2008-01-24, 7:24 pm

Mirko.Vukovic@gmail.com writes:

> Also check out emacs' else mode (an implementation of DEC's wonderful
> LSE editor). It does that as you type in the label.

Looks interesting, thanks!

Sebastian

Brian Hanson

2008-01-30, 7:24 pm

On Jan 23, 7:18 am, David Flower <DavJFlo...@aol.com> wrote:
> In another thread, I suggested that programmers should avoid using
> defaults when the same thing can be specified explicitly.
>
> It seems to me that posters could create a list of such situations, so
> here's a few to start off with.
>
> 1) Explicitly SAVE all variables that need to be saved, and no others.
>
> 2) Avoid using then left-to-right rule in the avaluation of
> expressions (e.g. X/Y*Z)
>
> 3) Explicitly declare all relevant file specifiers (DISP=,FORM= etc.)
>
> Let's have some comments and other examples
>
> Dave Flower
My personal bug is to require ONLY clauses on every USE statement. Besides
killing some inadvertent name conflicts, it lets you find where all the
subroutine names and imported constants came from -- nontrivial if there are a
lot of modules being used.

Brian Hanson

Andrew Chen

2008-01-30, 7:24 pm

Agree on end should have complete name. Emacs editor can do this
automatically.

6) Inside a module, declare everything as private, and everything
public must be explicitly declared. In another word, everything
default to be private.

7) Less or no comments. Use meaningful variable name of subroutine
names whenever possible. Obsolete comments can become poison. Try to
make the code readable first.

8) Try to generate other documents from source code.
Post processor that can pull documents out from the source code.

Fruit does one example for "executable requirement". The requirements
are written as test method name, or one variable spec inside the test
method.
Then a spec script can pull all of those in-code-requirement-document
out, to compile a document.
The benefits are obvious: 1) don't need to maintain a separate
reqirement document, or test plan document. 2) deadly clear about
which requirement is done, and which is not.

Example: ( http://fortranxunit.wiki.sourceforg...cation+by+Fruit
)

in code:

subroutine
test_**calculator_should_produce_4_when_
2_and_2_are_inputs**
use calculator, only: add
integer:: result

call add (2,2,result)
call assertEquals (4, result)
end subroutine
test_calculator_should_produce_4_when_2_
and_2_are_inputs

in report:

fruit/sample/test >rake spec
(in fruit/sample/test)

All executable specifications from tests:
calculator
--
-- calculator should produce 4 when 2 and 2 are inputs
-- calculation should produce 4.0 when 2.0 and 2.0
are
inputs
-- calculator should remember previous calculation results

Thanks
~Andrew Chen

Sponsored Links