Difference between revisions of "Coding Style Guide"
Jump to navigation
Jump to search
(import from github wiki) |
|||
| Line 1: | Line 1: | ||
| − | Some proposals on how to format and comment code; usual common Eiffel |
+ | 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. |
* try to choose feature names that would make code read (as much as) the English language. |
||
| − | * boolean |
+ | * 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? |
+ | * 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 |
+ | * 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 |
||
| − | * 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: |
||
| + | * use correct indentation |
||
| − | <pre><code>is_parameterless: BOOLEAN is |
||
| + | * <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 unqualified calls are possible (i. e. the *implicit* <code>Current</code> target, not the explicit <code>Current</code>! may use it); <code>{NONE}</code> is discouraged as the NONE adds no information at all. |
||
| − | -- Is the function without parameters? |
||
| + | * use 3 spaces for indentation, no TAB |
||
| − | 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. |
Feel free to make any proposal and improvements. |
||
Revision as of 01:07, 6 April 2013
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 queries should be named
is_...., e.g.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? 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.
- omit feature comments in case the feature name fully explains the feature
- use correct indentation
featureandcreationclauses should always have an explicit client list (Liberty will raise a warning otherwise). Of course it may be{ANY}. An empty list i.e.{}means that only unqualified calls are possible (i. e. the *implicit*Currenttarget, not the explicitCurrent! may use it);{NONE}is discouraged as the NONE adds no information at all.- use 3 spaces for indentation, no TAB
Feel free to make any proposal and improvements.