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

← Older revision		Revision as of 14:30, 20 May 2013
Line 278:		Line 278:

	<e>		<e>
	~~tangent_ from~~ (p: POINT): LINE		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.
Line 365:		Line 365:
	<e>		<e>
	feature -- Initialization		feature -- Initialization
	make is		make
	</e>		</e>

	<e>		<e>
	feature -- Access		feature -- Access
	item: G is		item: G
	</e>		</e>

	<e>		<e>
	feature -- Status report		feature -- Status report
	before: BOOLEAN is		before: BOOLEAN
	</e>		</e>

Line 384:		Line 384:
	<e>		<e>
	feature -- Element change		feature -- Element change
	put_left (v: G) is		put_left (v: G)
	</e>		</e>

	<e>		<e>
	feature -- Removal		feature -- Removal
	remove is		remove
	</e>		</e>

Line 551:		Line 551:
	make		make
	feature -- Initialization		feature -- Initialization
	make is		make
	-- Do something.		-- Do something.
	require		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:		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>		<e>
	accelerate (s: SPEED; t: REAL) is		accelerate (s: SPEED; t: REAL)
	-- Bring speed to s in at most t seconds.		-- Bring speed to s in at most t seconds.
	</e>		</e>
	<e>		<e>
	set_number (n: INTEGER) is		set_number (n: INTEGER)
	-- Make n the new value of number.		-- Make n the new value of number.
	</e>		</e>
Line 748:		Line 748:
	Rewrite the following header comments in the proper style:		Rewrite the following header comments in the proper style:
	<e>		<e>
	reorder (s: SUPPLIER; t: TIME) is		reorder (s: SUPPLIER; t: TIME)
	-- Reorders the current part from supplier s, to be delivered		-- 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.		-- on time t; this routine will only work if t is a time in the future.
Line 755:		Line 755:
	</e>		</e>
	<e>		<e>
	next_reorder_date: TIME is		next_reorder_date: TIME
	-- Yields the next time at which the current part is scheduled		-- Yields the next time at which the current part is scheduled
	-- to be reordered.		-- to be reordered.

Manus: Adding category

2009-07-21T06:08:28Z

Adding category

← 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.

Bmeyer: /* HEADER COMMENTS AND NOTE CLAUSES */

2009-03-03T18:58:03Z

HEADER COMMENTS AND NOTE CLAUSES

← Older revision		Revision as of 18:58, 3 March 2009
Line 259:		Line 259:
	and "note clauses" were called "indexing clauses"		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:		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:

Bmeyer: /* HEADER COMMENTS AND NOTE CLAUSES */

2009-03-03T18:57:23Z

HEADER COMMENTS AND NOTE CLAUSES

← Older revision		Revision as of 18:57, 3 March 2009
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.		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"		and "note clauses" were called "indexing clauses"

Bmeyer at 18:56, 3 March 2009

2009-03-03T18:56:50Z

← Older revision		Revision as of 18:56, 3 March 2009
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.		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.

			Terminology: in earlier Eiffel versions the keyword <b>indexing</b> was used instead of <b>note</b>,
			and "note clauses" were called "indexing clauses"

	Routine header comments: an exercise in corporate downsizing		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:		As you will remember, a class may have any number of feature clauses:
	<e>		<e>
	~~indexing~~		note
	</e>		</e>

Line 403:		Line 406:

	===Note clauses===		===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>		<e>
	note		note
Line 417:		Line 420:
	</e>		</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>		<e>
	note_term: note_value, note_value,		note_term: note_value, note_value,
	</e>		</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===		===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.		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>		<e>
	class C inherit -- [1]		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:		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 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.		*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.		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>		<e>
	~~indexing~~		note
	description: "Example for formating"		description: "Example for formating"
	class EXAMPLE inherit		class EXAMPLE inherit

Bmeyer: /* Indexing clauses */

2009-03-03T18:52:56Z

Indexing clauses

← Older revision		Revision as of 18:52, 3 March 2009
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.		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:		Similar to header comments but slightly more formal are indexing clauses, appearing at the beginning of a class:
	<e>		<e>
	~~indexing~~		note
	description: "Sequential lists, in chained representation"		description: "Sequential lists, in chained representation"
	names: "Sequence", "List"		names: "Sequence", "List"
Line 417:		Line 417:
	</e>		</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>		<e>
	~~indexing_term~~: ~~indexing_value~~, ~~indexing_value~~,		note_term: note_value, note_value,
	</e>		</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.		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.

Bmeyer: /* For boolean queries: */

2009-03-03T18:51:55Z

For boolean queries:

← Older revision		Revision as of 18:51, 3 March 2009
Line 157:		Line 157:

	====For boolean queries:====		====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.)		*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.)

			::Note: the variants without `is_' are also widely used, e.g. `prunable', but the `is_' form is now recommended.

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

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

2009-03-03T18:50:06Z

For non-boolean queries (attributes or functions):

← Older revision		Revision as of 18:50, 3 March 2009
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.		*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.		*infix "@": A synonym for item in a few cases, notably ARRAY.
			: -- Note: no longer necessary; use bracket alias instead. Still present in existing libraries.
	*count: Number of usable elements in a structure.		*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.		*capacity: Physical size allocated to a bounded structure, measured in number of potential elements. The invariant should include 0 <= count and count <= capacity.

Paulb: Formatted code

2008-06-10T15:44:45Z

Formatted code

← Older revision		Revision as of 15:44, 10 June 2008
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:		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>		<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>		</e>
	Note the indentation: one step further than the start of the routine body, so that the comment stands out.		Note the indentation: one step further than the start of the routine body, so that the comment stands out.
Line 271:		Line 271:

	<e>		<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>		</e>

Line 281:		Line 281:

	<e>		<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>		</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.)		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>		<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>		</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:		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>		<e>
	-- Tangent line to current circle from point p.		-- Tangent line to current circle from point p.
	</e>		</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:		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>		<e>
	-- Tangent to current circle from p.		-- Tangent to current circle from p.
	</e>		</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		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>		<e>
	-- Tangent from p.		-- Tangent from p.
	</e>		</e>

Paulb: Replaced is keyword with =

2008-06-10T15:42:45Z

Replaced is keyword with =

← Older revision		Revision as of 15:42, 10 June 2008
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:		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>		<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>		</e>