Coding Style Guide - Revision history

Hzwakenberg: spelling

2024-07-10T11:33:28Z

spelling

← Older revision		Revision as of 13:33, 10 July 2024
Line 4:		Line 4:
	* boolean queries should be named <code>is_....</code>, e.g. <code>is_empty</code>		* boolean queries should be named <code>is_....</code>, e.g. <code>is_empty</code>
	* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What does a command do? What's the meaning of a query? Avoid phrasing like "This feature opens a window", write instead "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".		* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What does a command do? What's the meaning of a query? Avoid phrasing like "This feature opens a window", write instead "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
−	* try to name feature argument prefixing them with generic English preposition (a_, an_, some_); this make ~~core~~-reading more fluent.	+	* try to name feature argument prefixing them with generic English preposition (a_, an_, some_); this make code-reading more fluent.
	* omit feature comments in case the feature name fully explains the feature		* omit feature comments in case the feature name fully explains the feature
	* use correct indentation		* use correct indentation

Hzwakenberg at 11:31, 14 March 2016

2016-03-14T11:31:50Z

← Older revision		Revision as of 13:31, 14 March 2016
Line 3:		Line 3:
	* try to choose feature names that would make code read (as much as) the English language.		* try to choose feature names that would make code read (as much as) the English language.
	* boolean queries should be named <code>is_....</code>, e.g. <code>is_empty</code>		* boolean queries should be named <code>is_....</code>, e.g. <code>is_empty</code>
−	* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What a command do? What's the meaning of a query? Avoid phrasing like "This feature opens a window", write instead "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".	+	* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What does a command do? What's the meaning of a query? Avoid phrasing like "This feature opens a window", write instead "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
	* try to name feature argument prefixing them with generic English preposition (a_, an_, some_); this make core-reading more fluent.		* try to name feature argument prefixing them with generic English preposition (a_, an_, some_); this make core-reading more fluent.
	* omit feature comments in case the feature name fully explains the feature		* omit feature comments in case the feature name fully explains the feature

Ramack at 23:07, 5 April 2013

2013-04-05T23:07:38Z

@@ Line 1: / Line 1: @@
-Some proposals on how to format and comment code; usual common Eiffel practises are reccomended of course.
+Some proposals on how to format and comment code; usual common Eiffel practices are recommended of course.
 * try to choose feature names that would make code read (as much as) the English language.
-* boolean queris should be named <code>is_....</code>, i.e. is_empty
+* boolean queries should be named <code>is_....</code>, e.g. <code>is_empty</code>
-* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What a command do? Wha't the meaning of a query? Avoid phrasing like "This feature opens a window", write insted "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
+* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What a command do? What's the meaning of a query? Avoid phrasing like "This feature opens a window", write instead "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
-* try to name feature argument prefixing them with generic english preposition (a_, an_, some_); this make core-reading more fluent IMHO. This is a style introduced in Gobo project and I learned to appreciate it working with Andreas in EWG,
+* try to name feature argument prefixing them with generic English preposition (a_, an_, some_); this make core-reading more fluent.
 Feel free to make any proposal and improvements.

Ramack: import from github wiki

2013-04-05T22:51:45Z

import from github wiki

New page

Some proposals on how to format and comment code; usual common Eiffel practises are reccomended of course.
* try to choose feature names that would make code read (as much as) the English language.
* boolean queris should be named <code>is_....</code>, i.e. is_empty
* Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What a command do? Wha't the meaning of a query? Avoid phrasing like "This feature opens a window", write insted "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
* try to name feature argument prefixing them with generic english preposition (a_, an_, some_); this make core-reading more fluent IMHO. This is a style introduced in Gobo project and I learned to appreciate it working with Andreas in EWG,
* As an exception to previous rules I suggest to avoid commenting for one-liners. Code like <code>is_parameterless: BOOLEAN is do Result:=(parameters_count=0) end</code> is self-explaining at least to me. Adding a description and formatting it with the usual Eiffel style-guide will make it looks like this:
<pre><code>is_parameterless: BOOLEAN is
-- Is the function without parameters?
do
Result:=(parameters_count=0)
end</code></pre>
In my humble opinion it does not add any further informations to the reader.

(Cyril) I don't like one-liners; code should always be correctly indented (the pretty-printer will do it anyway). But I agree that a comment that only paraphrases the name of the feature is useless. On the other hand I'd have added a postcondition:
<pre><code>ensure
definition: parameters_count = 0</code></pre>

* <code>feature</code> and <code>creation</code> clauses should always have an explicit client list (Liberty will raise a warning otherwise). Of course it may be <code>{ANY}</code>. An empty list i.e. <code>{}</code> means that only the *implicit* <code>Current</code> target (not the explicit <code>Current</code>!) may use it; <code>{NONE}</code> is discouraged and Liberty will raise a warning.

Feel free to make any proposal and improvements.