This repository has been archived by the owner on Apr 4, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 224
/
1st.html
149 lines (136 loc) · 4.88 KB
/
1st.html
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>WebScarab QA, sourcecode maintenance, draft</title>
</head>
<body>
<h1>abstract</h1>
This document describes the tools and methods used to keep
the java sourcecode of the WebScarab project clean, well-formed
and functional. As for now it is a draft and still needs to
be reviewed, extended and approved.
<h1>tools / libraries</h1>
<table>
<tr>
<th align="left">purpose</th>
<th align="left">name</th>
<th align="left">revision</th>
<th align="left">download location</th>
</tr>
<tr>
<td>building projects</td>
<td>ant</td>
<td>1.4.1</td>
<td>http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/src/jakarta-ant-1.4.1-src.tar.gz</td>
</tr>
<tr>
<td>testing code</td>
<td>junit</td>
<td>3.7</td>
<td>http://download.sourceforge.net/junit/junit3.7.zip</td>
</tr>
</table>
<h1>writing code</h1>
If some piece of code requires technical specifications of any
kind, the tech spec must be written and approved by the developer
team BEFORE the implementation process begins.<br />
If it shows up, that some interface must be changed, this has
to be announced. Again, the tech specs have to be rewritten first,
after approval interfaces may be changed.<br />
To assure that any piece of code is working exactly as one expects,
junit tests are used.<br /> The general contract is <b>to write tests first</b>,
i.e. once you defined some interface ("interface" means members,
methods and ctors of any class that have <code>public</code> scope)
you should define it's behaviour by writing explicit tests for it.<br />
<b>Example</b><br />
<code><pre>
class Foo {
int _x;
public Foo () {}
public int get() { }
public Object doSomething( Object val ) {}
}</pre></code><br />
Now let us assume you want the following behaviour:
<ul>
<li>a new Foo is initialized with x = 2</li>
<li>doSomething never returns null</li>
<li>every call to doSomething increments x</li>
</ul>
You would write junit tests like this:<br />
<code><pre>
void testInit () {
Foo f = new Foo();
assertEquals( 2, f.get() );
}
void testDoNotNull () {
Foo f = new Foo();
assertNotNull( f.doSomething( null ) );
}
void testDoInc () {
Foo f = new Foo();
f.doSomething( "val" );
assertEquals( 3, f.get() );
f.doSomething( "val" );
assertEquals( 4, f.get() );
}
</pre></code>
Now <b>AFTER</b> having defined the behaviour of the interface
you implement it:<br />
<code><pre>
class Foo {
int _x;
public Foo () { _x = 2; }
public int get() { return _x; }
public Object doSomething( Object val ) { return null == val ? "null" : val; }
}</pre></code><br />
Everything alright?<br />NO!<br />
Surely you noticed that the last test will fail, since _x is not
incremented on doSomething().<br />
By writing the test first you will discover immediately that something
goes wrong.<br />
If you do it this way around it is more likely that you do not forget to
test for a behaviour that you want to have.<br />
<h1>requirements for "stable" branches / releases</h1>
Until the first major release, no backwards compatibility for obsolete
interfaces will be provided.<br />
After the first major stable release, old interfaces have to be
maintained exactly for the next following minor release.<br />
Old interfaces have to be marked as deprecated and MUST BE REMOVED
AND SUBSTITUTED COMPLETELY with the next minor release.<br />
Only sourcecode that fulfils the following requirements will be allowed
to be published in "stable" releases or to be commited in "stable" CVS
branches:
<ul>
<li>complete test suite for the interface</li>
<li>complete jdoc for the interface</li>
<li>digitally signed (reviewed) by at least two developers</li>
</ul>
The last point is some assurance for the case that a developer who
wrote some awfully efficient, but yet cryptic code suddenly disappears.<br />
If every class (sourcefile) is at least known and understood by two
<i>active</i> developers, one can be sure that every part of the whole
system can be maintained by somebody.
<h1>source code format</h1>
<ul>
<li>exactly one tab per indentation level</li>
<li>members start with an underscore, local var's don't</li>
<li>complete jdoc</li>
<li></li>
</ul>
<h1>packaging</h1>
These are the rules for package naming:
<ul>
<li>every package is a subpackage of <code>org.owasp.webscarab</code></li>
<li>generic utility package: org.owasp.webscarab.util</li>
<li>datastore main package: org.owasp.webscarab.data</li>
<li>analyser main package: org.owasp.webscarab.analyse</li>
<li>spider main package: orq.owasp.webscarab.spider</li>
<li>attack generator main package: org.owasp.webscarab.attack</li>
<li>browser proxy main package: org.owasp.webscarab.proxy</li>
<li>client app main package: org.owasp.webscarab.ui</li>
</ul>
Every package may depend on ...util.<br />
All interfaces used to exchange data between the main packages must
be declared in the main packages and NOT in any subpackages.<br />
</body>
</html>