Eiffel style guidelines
17 views
Skip to first unread message
Eric Bezault
Apr 8, 2017, 2:49:50 AM4/8/17
to eiffel...@googlegroups.com
Hello,
In the Eiffel literature it is said that the header comment
of a non-boolean query should look like this:
count: INTEGER
-- Number of items
with no period at the end. But I can see that more and more
classes written by ISE use different style guidelines:
count: INTEGER
-- Number of items.
with a period. What is the rationale behind this change?
--
Eric Bezault
mailto:er...@gobosoft.com
http://www.gobosoft.com
In the Eiffel literature it is said that the header comment
of a non-boolean query should look like this:
count: INTEGER
-- Number of items
with no period at the end. But I can see that more and more
classes written by ISE use different style guidelines:
count: INTEGER
-- Number of items.
with a period. What is the rationale behind this change?
--
Eric Bezault
mailto:er...@gobosoft.com
http://www.gobosoft.com
Bertrand Meyer
Apr 8, 2017, 3:08:39 AM4/8/17
to eiffel...@googlegroups.com, me...@inf.ethz.ch
I do not remember the exact time (or can be sure 100%) but think the decision was taken in a discussion of the Ecma committee (although such rules are beyond the language standard) in favour of consistency.
-- BM
--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.
Visit this group at https://groups.google.com/group/eiffel-users.
For more options, visit https://groups.google.com/d/optout.
-- BM
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.
Visit this group at https://groups.google.com/group/eiffel-users.
For more options, visit https://groups.google.com/d/optout.
Colin Adams
Apr 8, 2017, 3:18:21 AM4/8/17
to eiffel...@googlegroups.com, me...@inf.ethz.ch
Consistent with what? Certainly not consistent with existing code.
Peter Horan
Apr 8, 2017, 3:21:35 AM4/8/17
to eiffel...@googlegroups.com
I think “uniformity” was the intention.
Peter Horan
Important Notice: The contents of this email are intended solely for the named addressee and are confidential; any unauthorised use, reproduction or storage of the contents is expressly prohibited. If you have received this email in error, please delete it and any attachments immediately and advise the sender by return email or telephone.
Deakin University does not warrant that this email and any attachments are error or virus free.
Eric Bezault
Apr 8, 2017, 4:13:14 AM4/8/17
to eiffel...@googlegroups.com, me...@inf.ethz.ch
On 4/8/2017 09:08, Bertrand Meyer wrote:
> I do not remember the exact time (or can be sure 100%) but think the decision was taken in a discussion of the Ecma committee (although such rules are beyond the language standard) in favour of consistency.
I don't remember such discussion.
> I do not remember the exact time (or can be sure 100%) but think the decision was taken in a discussion of the Ecma committee (although such rules are beyond the language standard) in favour of consistency.
I could not find anything in the minutes.
Alexander Kogtenkov
Apr 8, 2017, 4:18:45 AM4/8/17
to eiffel...@googlegroups.com, me...@inf.ethz.ch
When the style always using a period or a question mark at the end of every feature comment was discussed, I really did not like it to say in polite terms. The comments without any punctuation unless they were questions looked pretty reasonable to me.
However, since then I changed my mind. Firstly, if it a predicate, a question mark is added, like in a natural language. Why not follow the same convention for other queries and commands? I.e. a comment starts with a capital letter and ends with a punctuation mark (normally a period or a question mark). Before the rules was:
- add a question mark if it is a question;
- do not add anything otherwise.
However, it is not clear what to do if there are multiple sentences.
Secondly, the terminating period serves for me as an indicator of a complete comment, meaning that the author did not forget to finish the comment. This is essentially the same convention as used in natural languages as well. (Side note. There are different conventions used in source control systems: start with a capital letter or not, terminate with a period or not, use a bare infinitive or a past tense, e.g., compare the following commit messages:
- "add a new function"
- "Added a new function."
The second form looks like a finished phrase to me, but not the first one.)
Thirdly, what if there is not just a single-phrase comment? E.g.
read
-- Read a new portion of data and make it available in `data`
-- Set `error_code` to `0` on success or
-- to a non-zero error code otherwise
-- Update `has_error` accordingly
For me the version with periods would look more readable. Also, if there is proper punctuation, it opens a door for flexible formatting of comments in language tools (that seems a reasonable feature to me given that nowadays all web sites are using flexible formatting). Without punctuation the comment might become
-- Read a new portion of data and make it available in `data` Set
-- `error_code` to `0` on success or to a non-zero error code
-- otherwise Update `has_error` accordingly
that is not quite readable, and even becomes hard to understand correctly.
Of course, style guidelines could preserve the old conventions by describing special cases when multiple sentences are used, when comments are multiline, etc. For me, an alternative with a simpler set of rules without exceptions and special cases looks easier to follow.
Alexander Kogtenkov
However, since then I changed my mind. Firstly, if it a predicate, a question mark is added, like in a natural language. Why not follow the same convention for other queries and commands? I.e. a comment starts with a capital letter and ends with a punctuation mark (normally a period or a question mark). Before the rules was:
- add a question mark if it is a question;
- do not add anything otherwise.
However, it is not clear what to do if there are multiple sentences.
Secondly, the terminating period serves for me as an indicator of a complete comment, meaning that the author did not forget to finish the comment. This is essentially the same convention as used in natural languages as well. (Side note. There are different conventions used in source control systems: start with a capital letter or not, terminate with a period or not, use a bare infinitive or a past tense, e.g., compare the following commit messages:
- "add a new function"
- "Added a new function."
The second form looks like a finished phrase to me, but not the first one.)
Thirdly, what if there is not just a single-phrase comment? E.g.
read
-- Read a new portion of data and make it available in `data`
-- Set `error_code` to `0` on success or
-- to a non-zero error code otherwise
-- Update `has_error` accordingly
For me the version with periods would look more readable. Also, if there is proper punctuation, it opens a door for flexible formatting of comments in language tools (that seems a reasonable feature to me given that nowadays all web sites are using flexible formatting). Without punctuation the comment might become
-- Read a new portion of data and make it available in `data` Set
-- `error_code` to `0` on success or to a non-zero error code
-- otherwise Update `has_error` accordingly
that is not quite readable, and even becomes hard to understand correctly.
Of course, style guidelines could preserve the old conventions by describing special cases when multiple sentences are used, when comments are multiline, etc. For me, an alternative with a simpler set of rules without exceptions and special cases looks easier to follow.
Alexander Kogtenkov
Суббота, 8 апреля 2017, 10:18 +03:00 от Colin Adams <colinpa...@gmail.com>:
Eric Bezault
Apr 8, 2017, 4:48:58 AM4/8/17
to eiffel...@googlegroups.com
I just want to correct Alexander on the description of what the
Eiffel style guidelines used to say:
* boolean queries: question, with a question mark.
-- Is current object less than `other'?
* other queries: starting with a noun, no verb, no period.
-- Number of items
* commands: sentence starting with a verb, with a period.
-- Replace character at position `i' by `c'.
> mailto:er...@gobosoft.com <mailto:er...@gobosoft.com>
Eiffel style guidelines used to say:
* boolean queries: question, with a question mark.
-- Is current object less than `other'?
* other queries: starting with a noun, no verb, no period.
-- Number of items
* commands: sentence starting with a verb, with a period.
-- Replace character at position `i' by `c'.
> http://www.gobosoft.com
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Eiffel Users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to eiffel-users...@googlegroups.com
> <mailto:eiffel-users...@googlegroups.com>.
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Eiffel Users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to eiffel-users...@googlegroups.com
> Visit this group at https://groups.google.com/group/eiffel-users.
> For more options, visit https://groups.google.com/d/optout.
> For more options, visit https://groups.google.com/d/optout.
Jocelyn Fiat
Apr 8, 2017, 9:22:20 AM4/8/17
to Eiffel Users
On my side, I like ending any comment with a period. Because when I see such comment via any tool, if I see the period I am sure this is the end of the main comment.
Otherwise we never know if this was truncated, for instance just the first line of multiple lines comment.
-- Jocelyn
an email to eiffel-users+unsubscribe@googlegroups.com
<mailto:eiffel-users+unsubscrib...@googlegroups.com>.
Visit this group at https://groups.google.com/group/eiffel-users.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users+unsubscribe@googlegroups.com.
Colin Adams
Apr 8, 2017, 9:43:07 AM4/8/17
to Eiffel Users
Doesn't work. The first line of a multi-line comment may still be a complete sentence (if it's a command - if it's a query then the old convention was to terminate with a semi-colon).
<mailto:eiffel...@googlegroups.com>
an email to eiffel-users...@googlegroups.com
<mailto:eiffel-users...@googlegroups.com>.
Visit this group at https://groups.google.com/group/eiffel-users.
For more options, visit https://groups.google.com/d/optout.
--
Eric Bezault
mailto:er...@gobosoft.com
http://www.gobosoft.com
--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.
Visit this group at https://groups.google.com/group/eiffel-users.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "Eiffel Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eiffel-users...@googlegroups.com.
Reply all
Reply to author
Forward
0 new messages