Style Guidelines - Revision history

Conaclos: remove 'is' keyword and correct a feature name

2013-05-20T14:30:13Z

remove 'is' keyword and correct a feature name

Manus: Adding category

2009-07-21T06:08:28Z

Adding category

Bmeyer: /* HEADER COMMENTS AND NOTE CLAUSES */

2009-03-03T18:58:03Z

‎HEADER COMMENTS AND NOTE CLAUSES

Bmeyer: /* HEADER COMMENTS AND NOTE CLAUSES */

2009-03-03T18:57:23Z

‎HEADER COMMENTS AND NOTE CLAUSES

Bmeyer at 18:56, 3 March 2009

2009-03-03T18:56:50Z

Bmeyer: /* Indexing clauses */

2009-03-03T18:52:56Z

‎Indexing clauses

Bmeyer: /* For boolean queries: */

2009-03-03T18:51:55Z

‎For boolean queries:

Bmeyer: /* For non-boolean queries (attributes or functions): */

2009-03-03T18:50:06Z

‎For non-boolean queries (attributes or functions):

Paulb: Formatted code

2008-06-10T15:44:45Z

Formatted code

Paulb: Replaced is keyword with =

2008-06-10T15:42:45Z

Replaced is keyword with =

@@ Line 278: / Line 278: @@
 <e>
-tangent_ from (p: POINT): LINE
+tangent_from (p: POINT): LINE
          -- Return the tangent line to the current circle going through the point p,
          -- if the point is outside of the current circle.
@@ Line 365: / Line 365: @@
 <e>
 feature -- Initialization
-	make is
+	make
 </e>
 <e>
 feature -- Access
-	item: G is
+	item: G
 </e>
 <e>
 feature -- Status report
-	before: BOOLEAN is
+	before: BOOLEAN
 </e>
@@ Line 384: / Line 384: @@
 <e>
 feature -- Element change
-	put_left (v: G) is
+	put_left (v: G)
 </e>
 <e>
 feature -- Removal
-	remove is
+	remove
 </e>
@@ Line 551: / Line 551: @@
 	make
 feature -- Initialization
-	make is
+	make
 			-- Do something.
 		require
@@ Line 708: / Line 708: @@
 Comments appear in roman. This avoids any ambiguity when a feature name — which, according to the principles seen earlier, will normally be a word from ordinary language — or an argument name appears in a comment; the feature name will be in italics and hence will stand out. For example:
 <e>
-accelerate (s: SPEED; t: REAL) is
+accelerate (s: SPEED; t: REAL)
 		-- Bring speed to s in at most t seconds.
 </e>
 <e>
-set_number (n: INTEGER) is
+set_number (n: INTEGER)
 		-- Make n the new value of number.
 </e>
@@ Line 748: / Line 748: @@
 Rewrite the following header comments in the proper style:
 <e>
-reorder (s: SUPPLIER; t: TIME) is
+reorder (s: SUPPLIER; t: TIME)
 		-- Reorders the current part from supplier s, to be delivered
 		-- on time t; this routine will only work if t is a time in the future.
@@ Line 755: / Line 755: @@
 </e>
 <e>
-next_reorder_date: TIME is
+next_reorder_date: TIME
 		-- Yields the next time at which the current part is scheduled
 		-- to be reordered.

← Older revision		Revision as of 06:08, 21 July 2009
Line 1:		Line 1:
		+	[[Category:Coding Standards]]
	Style Guidelines that EiffelStudio developers should use and are not intended or suggestions for developing code with the Eiffel language. The guidelines are to promote consistency in API design, making EiffelStudio's code base more readable to all.		Style Guidelines that EiffelStudio developers should use and are not intended or suggestions for developing code with the Eiffel language. The guidelines are to promote consistency in API design, making EiffelStudio's code base more readable to all.

@@ Line 259: / Line 259: @@
   and "note clauses" were called "indexing clauses"
-Routine header comments: an exercise in corporate downsizing
+===Routine header comments: an exercise in corporate downsizing===
 Like those New York street signs that read “Don’t even think of parking here!”, the sign at the entrance of your software department should warn “Don’t even think of writing a routine without a header comment”. The header comment, coming just after the is for a routine, expresses its purpose concisely; it will be kept by the short and flat-short forms:

@@ Line 256: / Line 256: @@
 Although the formal elements of a class text should give as much as possible of the information about a class, they must be accompanied by informal explanations. Header comments of routines and feature clause answer this need together with the note clause of each class.
-  Terminology: in earlier Eiffel versions the keyword <b>indexing</b> was used instead of <b>note</b>,
+  '''Terminology''': in earlier Eiffel versions the keyword <b>indexing</b> was used instead of <b>note</b>,
   and "note clauses" were called "indexing clauses"

@@ Line 253: / Line 253: @@
 It is desirable, then, to group the constant declarations into a class, which can serve as ancestor to any class needing the constants (although some O-O designers prefer to use the client relation in this case). An example in the Base libraries is the class ASCII, which declares constant attributes for the different characters in the ASCII character set and associated properties.
-==HEADER COMMENTS AND INDEXING CLAUSES==
+==HEADER COMMENTS AND NOTE CLAUSES==
-Although the formal elements of a class text should give as much as possible of the information about a class, they must be accompanied by informal explanations. Header comments of routines and feature clause answer this need together with the indexing clause of each class.
+Although the formal elements of a class text should give as much as possible of the information about a class, they must be accompanied by informal explanations. Header comments of routines and feature clause answer this need together with the note clause of each class.
 Routine header comments: an exercise in corporate downsizing
@@ Line 347: / Line 350: @@
 As you will remember, a class may have any number of feature clauses:
 <e>
-indexing
+note
 </e>
@@ Line 403: / Line 406: @@
 ===Note clauses===
-Similar to header comments but slightly more formal are indexing clauses, appearing at the beginning of a class:
+Similar to header comments but slightly more formal are note clauses, appearing at the beginning of a class:
 <e>
 note
@@ Line 417: / Line 420: @@
 </e>
-Note clauses proceed from the same Self-Documentation principle that has led to built-in assertions and header comments: include as much as possible of the documentation in the software itself. For properties that do not directly appear in the formal text, you may include indexing entries, all of the form
+Note clauses proceed from the same Self-Documentation principle that has led to built-in assertions and header comments: include as much as possible of the documentation in the software itself. For properties that do not directly appear in the formal text, you may include note entries, all of the form
 <e>
 note_term: note_value, note_value,
 </e>
-where the note_term is an identifier and each indexing_value is some basic element such as a string, an integer and so on. Entries can indicate alternative names under which potential client authors might search for the class (names), contents type (contents), implementation choices (representation), revision control information, author information, and anything else that may facilitate understanding the class and retrieving it through keyword-based search tools — tools that support reuse and enable software developers to find their way through a potentially rich set of reusable components.
+where the note_term is an identifier and each note_value is some basic element such as a string, an integer and so on. Entries can indicate alternative names under which potential client authors might search for the class (names), contents type (contents), implementation choices (representation), revision control information, author information, and anything else that may facilitate understanding the class and retrieving it through keyword-based search tools — tools that support reuse and enable software developers to find their way through a potentially rich set of reusable components.
-Both the indexing terms and the indexing values are free-form, but the possible choices should be standardized for each project. A set of standard choices has been used throughout the Base libraries; the above example illustrates six of the most common entry kinds. Every class must have a description entry, introducing as index_value a string describing the role of the class, always expressed in terms of the instances (as Sequential listsº, not “this class describes sequential lists”, or “sequential list”, or “the notion of sequential list” etc.). Most significant class texts in this book — but not short examples illustrating a specific point — include the description entry.
+Both the note terms and the note values are free-form, but the possible choices should be standardized for each project. A set of standard choices has been used throughout the Base libraries; the above example illustrates six of the most common entry kinds. Every class must have a description entry, introducing as index_value a string describing the role of the class, always expressed in terms of the instances (as Sequential listsº, not “this class describes sequential lists”, or “sequential list”, or “the notion of sequential list” etc.). Most significant class texts in this book — but not short examples illustrating a specific point — include the description entry.
 ===Non-header comments===
@@ Line 473: / Line 476: @@
 You would not, however, use a line containing just if c or c end, since they include an operand together with something else, and are missing an ending operator in the first case and a starting operator in the second.
-Similarly, you may start a class, after the indexing clause, with
+Similarly, you may start a class, after the note clause, with
 <e>
 class C inherit					-- [1]
@@ Line 522: / Line 525: @@
 Here are the indentation levels for the basic kinds of construct, illustrated by the example on the facing page:
-*Level 0: the keywords introducing the primitive clauses of a class. This includes indexing (beginning of an indexing clause), class (beginning of the class body), feature (beginning of a feature clause, except if on the same line as class), invariant (beginning of an invariant clause, not yet seen) and the final end of a class.
+*Level 0: the keywords introducing the primitive clauses of a class. This includes note (beginning of a note clause), class (beginning of the class body), feature (beginning of a feature clause, except if on the same line as class), invariant (beginning of an invariant clause, not yet seen) and the final end of a class.
-*Level 1: beginning of a feature declaration; indexing entries; invariant clauses.
+*Level 1: beginning of a feature declaration; note entries; invariant clauses.
 *Level 2: the keywords starting the successive clauses of a routine. This includes require, local, do, once, ensure, rescue, end.
 *Level 3: the header comment for a routine or (for consistency) attribute; declarations of local entities in a routine; first-level instructions of a routine.
@@ Line 531: / Line 534: @@
 A check instruction is indented, together with the justifying comment that normally follows it, one level to the right of the instruction that it guards.
 <e>
-indexing
+note
 	description: "Example for formating"
 class EXAMPLE inherit

@@ Line 402: / Line 402: @@
 The categories cover a wide range of application domains, although for special areas you may need to add your own categories.
-===Indexing clauses===
+===Note clauses===
 Similar to header comments but slightly more formal are indexing clauses, appearing at the beginning of a class:
 <e>
-indexing
+note
 	description: "Sequential lists, in chained representation"
 	names: "Sequence", "List"
@@ Line 417: / Line 417: @@
 </e>
-Indexing clauses proceed from the same Self-Documentation principle that has led to built-in assertions and header comments: include as much as possible of the documentation in the software itself. For properties that do not directly appear in the formal text, you may include indexing entries, all of the form
+Note clauses proceed from the same Self-Documentation principle that has led to built-in assertions and header comments: include as much as possible of the documentation in the software itself. For properties that do not directly appear in the formal text, you may include indexing entries, all of the form
 <e>
-indexing_term: indexing_value, indexing_value,
+note_term: note_value, note_value,
 </e>
-where the indexing_term is an identifier and each indexing_value is some basic element such as a string, an integer and so on. Entries can indicate alternative names under which potential client authors might search for the class (names), contents type (contents), implementation choices (representation), revision control information, author information, and anything else that may facilitate understanding the class and retrieving it through keyword-based search tools — tools that support reuse and enable software developers to find their way through a potentially rich set of reusable components.
+where the note_term is an identifier and each indexing_value is some basic element such as a string, an integer and so on. Entries can indicate alternative names under which potential client authors might search for the class (names), contents type (contents), implementation choices (representation), revision control information, author information, and anything else that may facilitate understanding the class and retrieving it through keyword-based search tools — tools that support reuse and enable software developers to find their way through a potentially rich set of reusable components.
 Both the indexing terms and the indexing values are free-form, but the possible choices should be standardized for each project. A set of standard choices has been used throughout the Base libraries; the above example illustrates six of the most common entry kinds. Every class must have a description entry, introducing as index_value a string describing the role of the class, always expressed in terms of the instances (as Sequential listsº, not “this class describes sequential lists”, or “sequential list”, or “the notion of sequential list” etc.). Most significant class texts in this book — but not short examples illustrating a specific point — include the description entry.

@@ Line 157: / Line 157: @@
 ====For boolean queries:====
-*empty:	Is the structure devoid of elements?
+*is_empty:	Is the structure devoid of elements?
-*full:	Is there no more room in the representation to add elements? (Normally the same as count = capacity.)
+*is_full:	Is there no more room in the representation to add elements? (Normally the same as count = capacity.)
 *has:	Is a certain element present? (The basic membership test.)
-*extendible:	Can an element be added? (May serve as a precondition to extend.)
+*is_extendible:	Can an element be added? (May serve as a precondition to extend.)
-*prunable:	Can an element be removed? (May serve as a precondition to remove and prune.)
+*is_prunable:	Can an element be removed? (May serve as a precondition to remove and prune.)
-*readable:	Is there an accessible element? (May serve as precondition to item and remove.)
+*is_readable:	Is there an accessible element? (May serve as precondition to item and remove.)
-*writable:	Is it possible to change an element? (May variously serve as precondition to extend, replace, put etc.)
+*is_writable:	Is it possible to change an element? (May variously serve as precondition to extend, replace, put etc.)
 A few name choices which may seem strange at first are justified by considerations of clarity and consistency. For example prune goes with prunable and extend with extendible; delete and add might seem more natural, but then s l deletable and s l addable would carry the wrong connotation, since the question is not whether s can be deleted or added but whether we can add elements to it or delete elements from it. The verbs prune and extend, with the associated queries, convey the intended meaning.

@@ Line 152: / Line 152: @@
 *item:	The basic query for accessing an element: in ARRAY, the element at a given index; in STACK classes, the stack top; in QUEUE classes, the oldest element; and so on.
 *infix "@":	A synonym for item in a few cases, notably ARRAY.
 *count:	Number of usable elements in a structure.
 *capacity:	Physical size allocated to a bounded structure, measured in number of potential elements. The invariant should include 0 <= count and count <= capacity.

@@ Line 257: / Line 257: @@
 Like those New York street signs that read “Don’t even think of parking here!”, the sign at the entrance of your software department should warn “Don’t even think of writing a routine without a header comment”. The header comment, coming just after the is for a routine, expresses its purpose concisely; it will be kept by the short and flat-short forms:
 <e>
-distance_to_origin: REAL is
+distance_to_origin: REAL
-			-- Distance to point (0, 0)
+        -- Distance to point (0, 0)
-		local
+    local
-			origin: POINT
+        origin: POINT
-		do
+    do
-			!! origin
+        create origin
-			Result := distance (origin)
+        Result := distance (origin)
-		end
+    end
 </e>
 Note the indentation: one step further than the start of the routine body, so that the comment stands out.
@@ Line 271: / Line 271: @@
 <e>
-tangent_ from (p: POINT): LINE is
+tangent_ from (p: POINT): LINE
-		-- Return the tangent line to the current circle going through the point p,
+        -- Return the tangent line to the current circle going through the point p,
-		-- if the point is outside of the current circle.
+        -- if the point is outside of the current circle.
-	require
+    require
-		outside_circle: not has (p)
+        outside_circle: not has (p)
 </e>
@@ Line 281: / Line 281: @@
 <e>
-		-- The tangent line to the current circle going through the point p,
+        -- The tangent line to the current circle going through the point p,
-		-- if the point p is outside of the current circle
+        -- if the point p is outside of the current circle
 </e>
 Since the comment is not a sentence but simply a qualified noun, the final period disappears. Next we can get rid of the auxiliary words, especially the, where they are not required for understandability. Telegram-like style is desirable for comments. (Remember that readers in search of literary frills can always choose Proust novels instead.)
 <e>
-		--Tangent line to current circle from point p,
+        --Tangent line to current circle from point p,
-		-- if point p is outside current circle
+        -- if point p is outside current circle
 </e>
 The next mistake is to have included, in the second line, the condition for the routine’s applicability; the precondition, not has (p), which will be retained in the short form where it appears just after the header comment, expresses this condition clearly and unambiguously. There is no need to paraphrase it: this could lead to confusion, if the informal phrasing seems to contradict the formal precondition, or even to errors (a common oversight is a precondition of the form x >= 0 with a comment stating “applicable only to positive x”, rather than “non-negative”); and there is always a risk that during the software’s evolution the precondition will be updated but not the comment. Our example becomes:
 <e>
-		-- Tangent line to current circle from point p.
+        -- Tangent line to current circle from point p.
 </e>
 Yet another mistake is to have used the words line to refer to the result and point to refer to the argument: this information is immediately obvious from the declared types, LINE and POINT. With a typed notation we can rely on the formal type declarations — which again will appear in the short form — to express such properties; repeating them in the informal text brings nothing. So:
 <e>
-		-- Tangent to current circle from p.
+        -- Tangent to current circle from p.
 </e>
@@ Line 305: / Line 305: @@
 When you need to refer to the current object represented by a class, use phrasing such as current circle, current number and so on as above, rather than referring explicitly to the entity Current. In many cases, however, you can avoid mentioning the current object altogether, since it is clear to everyone who can read a class text that features apply to the current object. Here, for example, we just need
 <e>
-		-- Tangent from p.
+        -- Tangent from p.
 </e>

@@ Line 225: / Line 225: @@
 Instead, you should declare the corresponding constant attributes, and then, in the bodies of the routines that need the values, denote them through the attribute names:
 <e>
-US_state_count: INTEGER is 50
+US_state_count: INTEGER = 50
-File_not_found: STRING is "Cannot find file"
+File_not_found: STRING = "Cannot find file"
 </e>