Hi,
Thanks Celine to endorse this task.
We have already, a long time ago, discuss some of the coding
rules, and written them partially on some wiki pages. Other rules
are today usually implicit or are part of good practices. Some of
the rules are already coded in the Papyrus coding styles. Have you
check the proposed values (for example for the lenght of a line ) ?
But you are right, as there is more and more commiters, we can
write the rules more precisely. You provide a good starting point.
Here are my comments:
- First of all, we should define what is the name of an element:
is it its full name, its short name, or is it depending on the
context ?
- NAME-01
- I suppose that we speak of the short name. I am not in favor
of limiting the short name size. But I agree that a name
should not be too long.
- proposal: The short names of classes, methods, variables,
must not be too long (preferably less than 25 characters.).
- NAME-06 -
- I am not sure that package short names can contains dot.
Only package full name can be dot separated. But this is
implicit.
- I disagree with the use of concatenations or abbreviations.
This is meaningful for those who know them, but not for
peoples who want to understand the code.
- proposal: A package short name contains only lower
case letters. Package full name are separated by dots.
It's recommended to use short words. It is forbidden to
use concatenations or abbreviations instead of group of
words.
- NAME-07
- The package full names must begin by org.eclipse.papyrus.
- same for other rules (specify short or full ...)
- NAME-17
- A variable short name begins by a lower case letter.
- same for other rules (specify short or full ...)
- NAME-22
- I disagree with this rule. I am in favor of prefixing
boolean variables with 'is' (ex: isAvailable).
- PRES-10
- (A line must not be longer than 120 characters.)
- The value is too short !!! It should be longer (256 ? ). We
have longly discuss on that.
- PRES-12
- I disagree; Can we check the actual Papyrus rules ?
- PRES-16
- I disagree - extends and throws should be preferably placed
on the same line as the class short name.
- PRES-17
- I disagree. Normally, a method should not have a lot of
parameters :-) ...
- Indenting parameters as the body introduce confusions
between parameters and method variables. So, I prefer to have
a different indentation.
- PRES-19
- Empty lines greatly help to structure the code presentation.
We should not limit its use to 1 or two. There is some cases
where it is better to use 4 or 6 empty lines to improve the
readability. So, this rules
- proposal:
- at least one empty line should be inserted {...}
- At least Two empty lines must be inserted:
{...}
- PRES-22
- I don't understand this rule. What is a bracket in this
context ? Do you mean parenthesis ? In this case, I disagree.
We don't need space between (if, while, for, etc.) and
the following parenthesis.
- PRES-25
- (A space must be inserted after a cast instruction.)
- No, I disagree
- PRES-26
- (A space must be 'NOT' be inserted between two opening
brackets, or two closing brackets.)
- I disagree. There is cases where adding spaces improve
readability
- TIPS-03
- (Do not use generic import (with '*').)
- proposal: It is forbiden to use generic import
(with '*').
- TIPS-08
- (A Class with only private constructors must be declared as
final .)
- I am not sure of that.
- TIPS-11
- (It's mandatory to call explicitly the inherited constructor
when a constructor is overridden by a child Class, using the
super
key word.)
- I am not in favor of this rule. Do we really need that ?
- TIPS-25
- (All property and variable must be explicitly initialised at
its declaration, even with the default value.)
- I disagree. They should be initialised if needed. Otherwise,
we could have unnecessary assignment.
- TIPS-25 to 29
- I am not in favor of that. It is too restrictive.
- TIPS-33
- (A method must contain at most one return instruction.)
- I am not in favor of that. There is cases (ex: exit from a
loop) that are more readable with more than one return.
- proposal: A method must preferably contains only one return
instruction.
- TIPS-68
- (Foster the use of static, when possible.)
- I am not in favor of that in the case of Papyrus. Use of
static in Papyrus induce sharing variables between different
Papyrus instances. This should be done with care, and more
generally only for constants. Otherwise, we will have strange
behaviors ..;
- TIPS-73
- (Recursive algorithms must be avoid and replaced by
iterative algorithms when it's possible.)
- I am not in favor of that. Recursive algorithm are powerfull
when correctly used. It is not mandatory to systematically
replace them.
- proposal: remove this rule.
- ARCH8 to 9
- ??? Does this actually apply to Papyrus ?
- ARCH-09
- We have forbidden the use of reexport !! So this rule should
be changed
- ARCH-13
Is it planed to have rules for unit tests ? We actually have
some, but I am not sure that they are all written.
My two cents ...
Cedric
Céline JANSSENS a écrit :
Hi everyone,
Because of the increasing number of contributors, I suggest to
write down some development rules.
Before to make them active, I would like to have your feedback...
Those rules are based on another Eclipse project, so some rules
could be un-relevant for Papyrus.
I created a page on the wiki under the "Neon Work Description".
The Page is available here:
The Talk page is here:
Do not hesitate to interact on this topic.
Good review !
Céline
--
|
Céline JANSSENS
Software Engineer
+33 (0)2 44 47 23 23
|
|
Mail : cej@xxxxxxxxxxx
|
6 rue Léonard De Vinci - BP 0119 - 53001
LAVAL Cedex - FRANCE
www.all4tec.net
|
|
_______________________________________________
mdt-papyrus.dev mailing list
mdt-papyrus.dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/mdt-papyrus.dev
|