-
Notifications
You must be signed in to change notification settings - Fork 65
/
DEVELOPERS
198 lines (145 loc) · 8.5 KB
/
DEVELOPERS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
TODO make this file better. Finish the outline given at the bottom of this doc.
How To Check Out The Source Code
If you are using Eclipse
To check out the SQL Power Library and Power*Architect source into an Eclipse project:
1. If you don't yet have the Subversion feature available on your version of Eclipse, get Subclipse
2. Start Eclipse and create a new project (File -> New -> Project...)
3. Under the SVN folder, select Checkout Projects from SVN. If you don't see the SVN folder, go back to step 1. ;)
4. Create a new repository location to check out the SQL Power Library from. Power*Architect requires this project to build. The URL for the new repository is http://sqlpower-library.googlecode.com/svn/
5. To check out all of the latest source files for the SQL Power Library, select the trunk directory, then press next
6. Ensure that the "Check out as a project in the workspace" and "Head Revision" options are selected (they are the defaults), then click Finish.
7. Repeat steps 2-6 for Power*Architect, except use the following repository URL at step 4: http://power-architect.googlecode.com/svn/
Other Development Environments
Currently, everyone on the Architect team has chosen to use Eclipse. If you have a different favourite Java IDE, we'd be happy to post your instructions for checking out the Architect code here. Just post to the architect-developers list!
Command-line svn
If you just want to check out the source into a local directory or your development environment does not integrate with Subversion, use the command line svn tool:
For the SQL Power Library:
svn checkout http://sqlpower-library.googlecode.com/svn/trunk sqlpower-library
For Power*Architect:
svn checkout http://power-architect.googlecode.com/svn/trunk power-architect
How To Use The Ant Build File (build.xml)
Setting the build properties:
1. Create a copy the build.properties.example file in the same directory and rename it
to build.properties.
2. Set the sqlpower.library.home property to the directory where you have
the sqlpower-library project. The Power*Architect needs this to compile.
3. Set the build property to the directory where you would like
the architect to be compiled to.
The following section assumes that Eclipse is being used for development.
To build Power*Architect from the source files Apache Ant version 1.7 or higher
is required. See the following sub-section on how to install Apache Ant version 1.7 for
Eclipse. Once Ant 1.7 is installed Power*Architect can be run by using the
build.xml file. To run Power*Architect open the build.xml file and select the
target named run in the outline. Right click on the run target and select
Ant Build from the Run As menu option. Another target of interest is the alltest
target. This target will run the different test suites available with Power*Architect.
The alltest target can be run by right clicking on the alltest target and selecting
the Ant Build from the Run As menu option.
How To Install Apache Ant For Eclipse
Apache Ant is available at http://ant.apache.org/bindownload.cgi. To install Ant
1.7 into Eclipse first unzip and install Ant to your local machine. Then under
Eclipse's user preferences select the Ant runtime item in the list of preferences
on the left. Click on the Ant Home button and select the folder that you installed
Ant 1.7 into. Then click ok and Eclipse will use the new Ant.
Subscribe To Power*Architect Mailing Lists
There are two mailing lists for developers for Power*Architect which are hosted
on Google Groups. The first mailing list is the developers mailing list. The
developers list is for asking questions, giving comments and suggestions, or
any other concers that you may have while making modifications. The developer
mailing list is at http://groups.google.com/group/architect-developers. The
second mailing list is for commits to Power*Architect. The commits mailing
list is emailed every time a commit is done to the Power*Architect repository
with a comment about what was changed and a list of the modifications. The
commits mailing list is at http://groups.google.com/group/architect-commits.
Support Web Forum
For additional support you can visit the SQL Power forums at
http://www.sqlpower.ca/forum/forums/list.page.
Coding Standards.
We mainly use Sun's conventions for coding standards which are described here:
http://java.sun.com/docs/codeconv/
Our exceptions to Sun's rules, and some notes:
2.2 We don't use gnumake, so ignore the GNUmakefile thing
3.1.1 The non-javadoc introductory comment should now be the BSD license for
Architect and the SQLPower library it dependson
3.1.3 (4) Always put the log4j Logger declaration first, followed by a blank
line. No need to comment it.
4. Our tab size is currently 4, but we should all set our editors to use
spaces instead of tabs. 4 is not a standard tab size (8 is usual), and
tab stops of 4 will frustrate outside people trying to work with (or
simply read over) our code.
4.1 80 characters is a bit of an old-fashioned limitation, but excessively
long lines are difficult to read. Use your judgment here.
6.2 Sun's guide recommends declaring variables only at the beginning of a
block. I disagree: Code is more manageable and maintainable when variables
are declared as late as possible within a block.
6.3 I agree that you should initialize a variable when it's declared whenever
possible. However, when there is some logic associated with how to initialize
a value, it is best to declare it and leave it uninitialized at first, then in
each branch that follows, assign a value to the variable. This way, the
compiler will ensure that every possible path through the code ends up
initializing the variable. Example:
int foo;
if (bar < 10) {
foo = 12;
} else if (bar == 20) {
foo = 9;
} else {
foo = bar * 3;
}
System.out.println(foo); // This line will not compile unless foo has
// definitely been initialized (in this example, it has)
7.4 The last part shows an example of unacceptable code:
if (condition)
statement;
We also consider this unacceptable. However, we have a similar construction
which is acceptable: The "guard" idiom.
if (condition) return;
or
if (condition) break;
or
if (condition) continue;
This is only acceptable (in fact, it is the preferred form for expressing
the guard concept) if the return, break, or continue statement occurs on
the same line as the if. When the condition is long enough to warrant a
line break before the return, break, or continue statement, you must use braces:
// WRONG--conditionally executed code is on next line but not within braces
if (condition || condition2 || condition3)
return;
// CORRECT--Always use braces when the conditionally-executed code is not
// on the same line as the if
if (condition || condition2 || condition3) {
return;
}
7.9 Our preferred variable name for an exception in a catch block is "e" or
"ex", not "e1" as Eclipse likes to autogenerate.
Our preferred name for an event object in an event handler is also "e".
Therefore, you will often see catch blocks naming their exceptions "ex"
in Swing-related code to avoid confusion and naming conflicts.
9. (Interface naming) Additionally, avoid the temptation to use the word
"Interface" in an interface name, and the similar temptation to begin
an interface name with an I. Interface names should be given the cleanest,
most natural names possible. For instance, if you're creating an interface
and implementation for a beverage frobbing aparatus, you should name the
interface BeverageFrobber, and the implementation class BeverageFrobberImpl.
If there will be several implementations that would benefit from extending
an abstract base implementation, you would still create a BeverageFrobber
interface, then create an abstract class AbstractBeverageFrobber, and extend
it to the concrete classes named for their particular purpose
(BlendingBeverageFrobber, SippingBeverageFrobber, PouringBeverageFrobber, and so on).
The Wishlist
For developers new to Power*Architect that want to start making contributions to
Power*Architect there is a wishlist included with the source code that the developers
have put together.
Outline:
-how to check out sources
-subscribe to the mailing lists!
-commit log list
-developers discussion list
-support web forum
-learn the coding standards
-how to use the build file
-how to upgrade Ant to 1.7+ in eclipse
-read the WISHLIST
-how to create a patch
-how to submit a patch
-how to become a committer