* Another aspect of comments and coding standards
@ 1996-06-06 0:00 W. Wesley Groleau (Wes)
1996-06-07 0:00 ` Dave Marshall
0 siblings, 1 reply; 3+ messages in thread
From: W. Wesley Groleau (Wes) @ 1996-06-06 0:00 UTC (permalink / raw)
Brief rehash of recent suggestions (not necessarily all compatible):
1. Coding standards should make code more readable.
2. Coding standards should facilitate re-use.
3. Coding standards can be used to add semantics to the language,
thus reducing the need for comments.
4. Code should be understandable with neither the coding standard nor the LRM.
5. It's going to a silly extreme to expect code to be understandable
without the LRM.
4. Anything that can be expressed in the language instead of in comments
should be.
5. Comments should be used to express abstractions at a higher level.
6. Comments should be used when the code isn't clear.
7. The code should always be clear.
I didn't do that just to re-start the argument. Rather, I seek opinions
on a related issue:
When does using a language feature become a "clever trick" to be avoided?
What is the threshold between (1) keeping the actual code simple but not clear
(and filling in with comments) and (2) allowing complexity of code to
eliminate the need for those comments?
For example, which is better and why:
if Value in Limit_1 .. Limit_2 then if Limit_2 >= Limit_1 and
-- note possibility of null range Value >= Limit_1 and
-- [ see LRM 3.5(4) & 4.5.2(27-32) ] Value <= Limit_2 then
Examples with other language features also welcome.
I'm withholding my opinion lest those who agree keep silent. :-)
---------------------------------------------------------------------------
W. Wesley Groleau (Wes) Office: 219-429-4923
Magnavox - Mail Stop 10-40 Home: 219-471-7206
Fort Wayne, IN 46808 elm (Unix): wwgrol@pseserv3.fw.hac.com
---------------------------------------------------------------------------
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Another aspect of comments and coding standards
1996-06-07 0:00 ` Dave Marshall
@ 1996-06-07 0:00 ` Robert Dewar
0 siblings, 0 replies; 3+ messages in thread
From: Robert Dewar @ 1996-06-07 0:00 UTC (permalink / raw)
Dave Marshall says
"For instance, I am a little bit uncomfortable with the use of the
anonymous subtype used in the membership test."
This is a very good point, particularly applicable to the case of
enumeration types. A weakness in Ada is that enumeration types are
always ordered, and you cannot hide this ordering from a client.
Logically what is often done is to arrange a set of enumeration values
in order so that subtypes dfining appropriate subclasses
can be defined as part of the same abstraction.
However, there is no way, other than coding standards, to avoid a client
noticing that today three values happen to be contiguous and replacing
if a = enum1 or a = enum2 or a = enum3 then
by
if a in enum1 .. enum3 then
Now of course you have a maintenance headache, because at the abstraction
level the specific order of the enumeration literals was not defined.
A reasonable coding standard is to absolutely forbid ranges in membership
tests for enumeration types (there is no similar objection for integer
types, this comment applies only to enumeration types).
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Another aspect of comments and coding standards
1996-06-06 0:00 Another aspect of comments and coding standards W. Wesley Groleau (Wes)
@ 1996-06-07 0:00 ` Dave Marshall
1996-06-07 0:00 ` Robert Dewar
0 siblings, 1 reply; 3+ messages in thread
From: Dave Marshall @ 1996-06-07 0:00 UTC (permalink / raw)
"W. Wesley Groleau (Wes)" <wwgrol@PSESERV3.FW.HAC.COM> writes:
>When does using a language feature become a "clever trick" to be avoided?
>What is the threshold between (1) keeping the actual code simple but not clear
>(and filling in with comments) and (2) allowing complexity of code to
>eliminate the need for those comments?
>For example, which is better and why:
> if Value in Limit_1 .. Limit_2 then if Limit_2 >= Limit_1 and
> -- note possibility of null range Value >= Limit_1 and
> -- [ see LRM 3.5(4) & 4.5.2(27-32) ] Value <= Limit_2 then
>Examples with other language features also welcome.
>I'm withholding my opinion lest those who agree keep silent. :-)
Well, first, if you're holding up membership tests as a "clever
trick," then we're all doomed.
Secondly, regarding your examples: I would hope that no one in his
right mind would be inserting LRM references in his code. One
shudders to think about how one might be looking through pages and
pages of comments looking for the occasional statement.
[Before I go on, the little critic in me wants to point out that if
Value >= Limit_1 and Value <= Limit_2, then we know that Limit_2 >=
Limit_2, so your second example has a redundancy.]
In the abstract, I prefer the first example (without the LRM comments,
of course). I don't regard this as a clever trick in the slightest,
given that it's got several paragraphs devoted to it in the LRM. If
someone looking at this code in the future doesn't immediately
recognize this as a membership test (and where to go look in the LRM
if necessary), he should find other employment.
In other words, every instance of source code shouldn't be expected to
provide tutorial information for inexperienced programmers.
That having been said, let me address the issue of context in which
such a "clever trick" appears. This would apply to almost every
clever trick used, so my continued use of the membership test
shouldn't be construed to mean that I think these remarks are limited
to membership tests.
With a little bit of effort, we can usually make "clever tricks" very
readable and understandable.
For instance, I am a little bit uncomfortable with the use of the
anonymous subtype used in the membership test. I'd rather see
Some_Block_Name:
declare
subtype Legal_Values is Some_Type range Limit_1 .. Limit_2;
begin
if Value in Legal_Values then
...
end if;
end Some_Block_Name;
By choosing appropriate names, we can make what's going on clear to
even the most dense.
Furthermore, we might choose to hide our clever tricks within the
abstraction we're implementing. For instance (and I agree this is
crude, but I hope it illustrates my point):
Instead of:
High_Limit := Float(220 - Age) * 0.85;
Low_Limit := Float(220 - Age) * 0.75;
if Heartbeat in Integer(Low_Limit) .. Integer(High_Limit) then
Do_Something;
end if;
we might have
if Is_Aerobic(Pulse => Heartbeat,
Age => My_Age) then
Do_Something;
end if;
--
Dave Marshall
dmarshal@netcom.com
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~1996-06-07 0:00 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
1996-06-06 0:00 Another aspect of comments and coding standards W. Wesley Groleau (Wes)
1996-06-07 0:00 ` Dave Marshall
1996-06-07 0:00 ` Robert Dewar
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox