* 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-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
* 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
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