jacoco/org.jacoco.doc/docroot/doc/conventions.html - toolchain/jack - Git at Google

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   <link rel="stylesheet" href=".resources/doc.css" charset="UTF-8" type="text/css" />
   <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
   <title>JaCoCo - Development Conventions</title>
 </head>
 <body>

 <div class="breadcrumb">
   <a href="../index.html" class="el_report">JaCoCo</a> &gt;
   <a href="index.html" class="el_group">Documentation</a> &gt;
   <span class="el_source">Development Conventions</span>
 </div>
 <div id="content">

 <h1>Development Conventions</h1>

 <p>
   Efficient team work that produces high-quality software requires a common set
   of rules.
 </p>

 <h2>Consistent Source Tree</h2>

 <p>
   Update your sources and run the build locally before every check-in. Commit
   only if the build succeeds.
 </p>

 <p>
   Documentation is part of the product. Whenever you implement a new feature or
   change existing behavior make sure to update all corresponding JavaDoc as well
   as other documentation with the same change set. The product should always be
   in a consistent state. For every change the following items should be checked:
 </p>

 <ul>
   <li>Corresponding JavaDoc.</li>
   <li>Documentation referring to the modified concepts, interfaces or
     implementation.</li>
   <li>New features, bug fixes and modified behavior should be enlisted in the
     <code>org.jacoco.doc/docroot/doc/changes.html</code> file together with
     the corresponding issue tracker id.</li>
 </ul>

 <h2>Design for Integration</h2>

 <p>
   The primary focus of the JaCoCo project is to provide a code coverage library.
   Integrators may want to embed JaCoCo in different tools and environments with
   very different usage scenarios. Therefore following aspects should be considered:
 </p>

 <p>
   <b>Documentation:</b> All APIs should be properly documented on different
   levels of granularity:
 </p>

 <ul>
   <li>General usage</li>
   <li>Bundle summary</li>
   <li>Package summary</li>
   <li>Type description</li>
   <li>Member description</li>
 </ul>

 <p>
   <b>Proper Units:</b> All APIs and internal implementation classes should form proper
   units with well defined responsibilities and dependencies. Each class and method
   should focus on a single concept. It should be possible to use different aspects
   separately.
 </p>

 <p>
   <b>Abstraction:</b> All APIs must  use the most general abstractions possible. For instance
   reading binary data should rely on the <code>java.io.InputStream</code> interface, not
   on a <code>java.io.File</code> object.
 </p>

 <p>
   <b>System Dependencies:</b> Avoid any dependencies to the local file system, network
   resources, threads, processes etc.
 </p>

 <h2>Test Driven Development</h2>

 <p>
   All code added to JaCoCo should have corresponding JUnit test cases. Ideally tests
   are developed before or along with the actual implementation:
 </p>

 <ul>
   <li>Every new feature should be verified by test cases.</li>
   <li>Modified behavior should also be reflected by test cases.</li>
   <li>Ideally for every reported bug a reproducer is added to the unit tests.</li>
 </ul>

 <h2>Keep an Eye on License Issues</h2>

 <p>
   All code included with JaCoCo must conform to the EPL license.
 </p>

 <ul>
   <li>
     Every committer and contributor must agree that all code will be published
     under EPL. He or she must be the original author and must have the
     permission to contribute code to JaCoCo, for example if such a permission
     is required by the employer.
   </li>
   <li>
     Every third party content must be enlisted in the corresponding
     <code>about.html</code> file along with its license.
   </li>
   <li>
     Every third party content included with the JaCoCo distribution must be
     enlisted in the <code>org.jacoco.doc/docroot/doc/license.html</code> file
     and the corresponding <code>about.html</code> file along with its license.
   </li>
   <li>
     Every source file (Java, Build Script, DTD) must have a
     <a href="http://www.eclipse.org/legal/copyrightandlicensenotice.php">EPL
     license notice</a>. The initial contributor should be listed. In case of
     significant changes or additions additional contributors should also
     be listed.
   </li>
 </ul>

 </div>
 <div class="footer">
   <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
   <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
 </div>

 </body>
 </html>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<link rel="stylesheet" href=".resources/doc.css" charset="UTF-8" type="text/css" />
	<link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
	<title>JaCoCo - Development Conventions</title>
	</head>
	<body>

	<div class="breadcrumb">
	<a href="../index.html" class="el_report">JaCoCo</a> >
	<a href="index.html" class="el_group">Documentation</a> >
	<span class="el_source">Development Conventions</span>
	</div>
	<div id="content">

	<h1>Development Conventions</h1>

	<p>
	Efficient team work that produces high-quality software requires a common set
	of rules.
	</p>

	<h2>Consistent Source Tree</h2>

	<p>
	Update your sources and run the build locally before every check-in. Commit
	only if the build succeeds.
	</p>

	<p>
	Documentation is part of the product. Whenever you implement a new feature or
	change existing behavior make sure to update all corresponding JavaDoc as well
	as other documentation with the same change set. The product should always be
	in a consistent state. For every change the following items should be checked:
	</p>

	<ul>
	<li>Corresponding JavaDoc.</li>
	<li>Documentation referring to the modified concepts, interfaces or
	implementation.</li>
	<li>New features, bug fixes and modified behavior should be enlisted in the
	<code>org.jacoco.doc/docroot/doc/changes.html</code> file together with
	the corresponding issue tracker id.</li>
	</ul>

	<h2>Design for Integration</h2>

	<p>
	The primary focus of the JaCoCo project is to provide a code coverage library.
	Integrators may want to embed JaCoCo in different tools and environments with
	very different usage scenarios. Therefore following aspects should be considered:
	</p>

	<p>
	<b>Documentation:</b> All APIs should be properly documented on different
	levels of granularity:
	</p>

	<ul>
	<li>General usage</li>
	<li>Bundle summary</li>
	<li>Package summary</li>
	<li>Type description</li>
	<li>Member description</li>
	</ul>

	<p>
	<b>Proper Units:</b> All APIs and internal implementation classes should form proper
	units with well defined responsibilities and dependencies. Each class and method
	should focus on a single concept. It should be possible to use different aspects
	separately.
	</p>

	<p>
	<b>Abstraction:</b> All APIs must use the most general abstractions possible. For instance
	reading binary data should rely on the <code>java.io.InputStream</code> interface, not
	on a <code>java.io.File</code> object.
	</p>

	<p>
	<b>System Dependencies:</b> Avoid any dependencies to the local file system, network
	resources, threads, processes etc.
	</p>

	<h2>Test Driven Development</h2>

	<p>
	All code added to JaCoCo should have corresponding JUnit test cases. Ideally tests
	are developed before or along with the actual implementation:
	</p>

	<ul>
	<li>Every new feature should be verified by test cases.</li>
	<li>Modified behavior should also be reflected by test cases.</li>
	<li>Ideally for every reported bug a reproducer is added to the unit tests.</li>
	</ul>

	<h2>Keep an Eye on License Issues</h2>

	<p>
	All code included with JaCoCo must conform to the EPL license.
	</p>

	<ul>
	<li>
	Every committer and contributor must agree that all code will be published
	under EPL. He or she must be the original author and must have the
	permission to contribute code to JaCoCo, for example if such a permission
	is required by the employer.
	</li>
	<li>
	Every third party content must be enlisted in the corresponding
	<code>about.html</code> file along with its license.
	</li>
	<li>
	Every third party content included with the JaCoCo distribution must be
	enlisted in the <code>org.jacoco.doc/docroot/doc/license.html</code> file
	and the corresponding <code>about.html</code> file along with its license.
	</li>
	<li>
	Every source file (Java, Build Script, DTD) must have a
	<a href="http://www.eclipse.org/legal/copyrightandlicensenotice.php">EPL
	license notice</a>. The initial contributor should be listed. In case of
	significant changes or additions additional contributors should also
	be listed.
	</li>
	</ul>

	</div>
	<div class="footer">
	<span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
	<a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
	</div>

	</body>
	</html>