Differences

This shows you the differences between two versions of the page.

--- ulam_programming_conventions [2015/05/26 09:07] – [Utils and Services Declarations] ackley
+++ ulam_programming_conventions [2015/05/26 09:28] (current) – ackley
@@ Line 7: / Line 7: @@
 In the standard library, you can find things like ''WindowServices'' and ''DebugUtils'', both of which, viewed generally, have similar purposes: They provide methods you can call to do useful things.  So, why are some named '*Services' while are named '*Utils'?  Here's the key convention: Things suffixed with ''Utils'' should be size 0, while things suffixed with ''Services'' have a non-zero size.
-=== The EventWindow Exception ===
+=== The EventWindow and Random Exceptions ===
 Of course the elephant in the standard library is ''EventWindow''.  That name violates this convention, because it has neither 'Utils' nor 'Services' as a suffix; it gets away with the violation because it predates the whole naming convention.  But, since it is size 0, we should //think// of it like ''EventWindowUtils'' and not ''<del>EventWindowServices</del>''.
+Exactly the same is true for ''Random'', which we should think of as ''RandomUtils''.
 ==== Utils and Services Declarations ====
@@ Line 18: / Line 19: @@
 <code - Evaporator.ulam>
+/** \symmetries all */
 element Evaporator {
   EventWindow ew;
@@ Line 27: / Line 29: @@
 <code>
+/** \symmetries all */
 element Evaporator {
   Void behave() {
@@ Line 36: / Line 39: @@
 even though, in this case, both versions behave identically.
-The reasoning for this **Make *Utils data members** guidance has an obvious point and a subtle point:
+The reasoning for this **Make *Utils data members** guidance has both obvious and subtle points.
-The obvious point is that since a *Utils is size 0, it doesn't impact the atomic bit budget at all, so it's harmless to make them data members.  Furthermore, placing them as data members makes them available to all methods with a single declaration, and can provide a systematic place (e.g., at the top of the class) for all *Utils declarations.
+An obvious point is that since a *Utils is size 0, it doesn't impact the atomic bit budget at all, so it's harmless to make them data members, while conversely, a *Services data member //does// impact the bit budget, so we don't want to do it thoughtlessly.  Furthermore, placing *Utils as data members makes them available to all methods with a single declaration, and also provides a systematic place (at or near the top of the class) for all *Utils declarations.
-The subtle point is that even though a *Utils is size 0, when a *Utils method is called, the ''self'' object passed into the called method can differ depending on how the *Utils was declared.  For example, this definition:
+A subtle point is that even though a *Utils is size 0, when a *Utils method is called, the ''self'' object passed into the called method can differ depending on how the *Utils was declared.  And that can affect how the called *Utils method behaves.  For example, this definition:
 <code - Announcer.ulam>
@@ Line 55: / Line 58: @@
   20150526025907-258: 10AEPS [FFE892F7]MSG: @(31, 4) of [1,1]: (An)
-in which the ''PrintContext'' method reports the event position as well as the symbol ''(An)'' of the ''self'' object it was called on.  That's not terribly useful, but compare that output to this similar definition:
+in which the ''printContext'' method reports the event position as well as the symbol ''(An)'' of the ''self'' object it was called on.  That's not terribly useful, but consider this very similar definition:
   element Announcer {
@@ Line 70: / Line 73: @@
   20150526030050-258: 4AEPS [FFE91807]MSG: @(17,24) of [2,1]: (E)
-What has happened?  How can PrintContext be reporting type ''(E)'' (for Empty) when we //know// there was an ''Announcer'' atom in the center of the event window -- there must have been, or else the Announcer's behave method wouldn't have been called?  The answer is that when ''DebugUtils'' is declared as a local variable, it is not associated with the atom at the center of the event window, it is associated with a scratch atom living on the function call stack, that happens to have type Empty.
+What has happened?  How can printContext be reporting type ''(E)'' (for Empty) when we //know// there was an ''Announcer'' atom in the center of the event window -- there must have been, or else the Announcer's behave method wouldn't have been called?  The answer is that when ''DebugUtils'' is declared as a local variable, it is not associated with the atom at the center of the event window, it is associated with a scratch atom living on the function call stack, that happens to have type Empty.
-Following the **Make *Utils data members** ensures that all *Utils will be associated with the event window center, which is almost always either what you want, or of no harm.
+Many *Utils methods never examine their ''self'' object so this difference is moot.  For example, neither ''EventWindow'' nor  ''Random'' (both size 0 quarks) do.  But some do, and
+following the **Make *Utils data members** ensures that all *Utils method calls will be associated with caller's underlying storage, which is almost always either what you want, or of no harm.