blob: f7a480cdc1a7a563dfacd775531a96b996371ea9 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Apache TomEE</title>
<meta name="description"
content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
<meta name="author" content="Luka Cvetinovic for Codrops" />
<link rel="icon" href="../favicon.ico">
<link rel="icon" type="image/png" href="../favicon.png">
<meta name="msapplication-TileColor" content="#80287a">
<meta name="theme-color" content="#80287a">
<link rel="stylesheet" type="text/css" href="../css/normalize.css">
<link rel="stylesheet" type="text/css" href="../css/bootstrap.css">
<link rel="stylesheet" type="text/css" href="../css/owl.css">
<link rel="stylesheet" type="text/css" href="../css/animate.css">
<link rel="stylesheet" type="text/css" href="../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="../fonts/eleganticons/et-icons.css">
<link rel="stylesheet" type="text/css" href="../css/jqtree.css">
<link rel="stylesheet" type="text/css" href="../css/idea.css">
<link rel="stylesheet" type="text/css" href="../css/cardio.css">
<script type="text/javascript">
<!-- Matomo -->
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
/* We explicitly disable cookie tracking to avoid privacy issues */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function () {
var u = "//matomo.privacy.apache.org/";
_paq.push(['setTrackerUrl', u + 'matomo.php']);
_paq.push(['setSiteId', '5']);
var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
g.async = true;
g.src = u + 'matomo.js';
s.parentNode.insertBefore(g, s);
})();
<!-- End Matomo Code -->
</script>
</head>
<body>
<div class="preloader">
<img src="../img/loader.gif" alt="Preloader image">
</div>
<nav class="navbar">
<div class="container">
<div class="row"> <div class="col-md-12">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/" title="Apache TomEE">
<span>
<img
src="../img/apache_tomee-logo.svg"
onerror="this.src='../img/apache_tomee-logo.jpg'"
height="50"
>
</span>
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right main-nav">
<li><a href="../docs.html">Documentation</a></li>
<li><a href="../community/index.html">Community</a></li>
<li><a href="../security/security.html">Security</a></li>
<li><a class="btn btn-accent accent-orange no-shadow" href="../download.html">Downloads</a></li>
</ul>
</div>
<!-- /.navbar-collapse -->
</div></div>
</div>
<!-- /.container-fluid -->
</nav>
<div id="main-block" class="container main-block">
<div class="row title">
<div class="col-md-12">
<div class='page-header'>
<h1>Writing Presentable Examples</h1>
</div>
</div>
</div>
<div class="row">
<div class="col-md-12">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Writing an example is easy.
Any example is a good one.
The more the better.</p>
</div>
<div class="paragraph">
<p>Writing examples that can be used in a presentations is hard.</p>
</div>
<div class="paragraph">
<p>Some basic guidelines of writing examples:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>focus on one idea per example</p>
</li>
<li>
<p>keep examples short</p>
<div class="ulist">
<ul>
<li>
<p>one test case</p>
</li>
<li>
<p>minimal code to make the point</p>
</li>
</ul>
</div>
</li>
<li>
<p>avoid showing an entire API in one example, if possible</p>
</li>
<li>
<p>be conscious of the cost of "setting the stage"</p>
</li>
<li>
<p>if examples get too big, split it</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_noise_vs_signal">Noise vs signal</h2>
<div class="sectionbody">
<div class="paragraph">
<p>It takes time to learn the example scenario (noise).
You need to learn the scenario before you can start to see the important parts (signal).</p>
</div>
<div class="paragraph">
<p>Be very mindful of your noise to signal ratio.</p>
</div>
<div class="paragraph">
<p>Example scenarios do not need to be believable and should not be elaborate.
Get to the point in as few classes as possible.</p>
</div>
<div class="paragraph">
<p>You should be able to explain the entire example in two minutes.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_five_ways_to_do_the_same_thing">Five ways to do the same thing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If there are five ways to do the same thing, avoid making five different scenarios.
Copy the example to a new directory, and tweak it to show the variation.</p>
</div>
<div class="paragraph">
<p>So say you used objects <code>Green</code>, <code>Square</code> and <code>Checkers</code> to show the basic concept and you wish to show the next variation of that same concept.
It is tempting to add to the same example objects <code>Yellow</code>, <code>Triangle</code> and <code>PolkaDots</code>.</p>
</div>
<div class="paragraph">
<p>Avoid that.
Copy <code>Green</code>, <code>Square</code> and <code>Checkers</code> to a new example, change the package name, and update the few lines needed to show the difference.</p>
</div>
<div class="paragraph">
<p>Where does your eye focus?</p>
</div>
<div class="ulist">
<ul>
<li>
<p>934 + 55 = 989</p>
</li>
<li>
<p>513 - 19 = 494</p>
</li>
<li>
<p>468 * 44 = 20592</p>
</li>
<li>
<p>708 / 89 = 7</p>
</li>
<li>
<p>401 % 63 = 23</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>How about now?</p>
</div>
<div class="ulist">
<ul>
<li>
<p>102 + 35 = 137</p>
</li>
<li>
<p>102 - 35 = 67</p>
</li>
<li>
<p>102 * 35 = 3570</p>
</li>
<li>
<p>102 / 35 = 2</p>
</li>
<li>
<p>102 % 35 = 32</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The intent of the second set of numbers can be easily guessed.
An explanation that it is about the math operators confirms that and locks it in your brain.</p>
</div>
<div class="paragraph">
<p>When presenting, you only get so much time to show people ideas.
If they have to learn a new set of names and understand their relationship on each tiny variation, it severely impacts their ability to see what is supposed to be the same and what is supposed to be different.
As a presenter this means you must show less and what you do show will be shown less clearly.</p>
</div>
<div class="paragraph">
<p>When names and scenarios are consistent, the variations jump out quickly and with impact.</p>
</div>
<div class="paragraph">
<p>If there are five ways to do the same thing, show the same thing five different ways.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_short_class_names">Short Class Names</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You don&#8217;t need to document the example with the class name.
Class names that are a mouthful cannot be effectively used in presentations or screencasts.</p>
</div>
<div class="paragraph">
<p>Try to stick with one or two word class names.
Three tops.</p>
</div>
<div class="paragraph">
<p>Avoid:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>BeanWithTwoDecoratorsAndOneProducerMethod</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Try instead:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>BlueBean</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Shorter names can be easier for all sorts of reasons.
Less words to keep "floating in the head" when trying to truly see an example.</p>
</div>
<div class="paragraph">
<p>Using the numbers from the previous section, which is easier?</p>
</div>
<div class="ulist">
<ul>
<li>
<p>102 + 35 = 137</p>
</li>
<li>
<p>102 - 35 = 67</p>
</li>
<li>
<p>102 * 35 = 3570</p>
</li>
<li>
<p>102 / 35 = 2</p>
</li>
<li>
<p>102 % 35 = 32</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Or:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>12 + 3 = 15</p>
</li>
<li>
<p>12 - 3 = 9</p>
</li>
<li>
<p>12 * 3 = 36</p>
</li>
<li>
<p>12 / 3 = 4</p>
</li>
<li>
<p>12 % 3 = 0</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>There&#8217;s a finite amount people can keep in their head, save space for the important stuff.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div style="margin-bottom: 30px;"></div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-6 text-center-mobile">
<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
<h5 class="light regular light-white">"A good application in a good server"</h5>
<ul class="social-footer">
<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
</ul>
<h5 class="light regular light-white">
<a href="../privacy-policy.html" class="white">Privacy Policy</a>
</h5>
</div>
<div class="col-sm-6 text-center-mobile">
<div class="row opening-hours">
<div class="col-sm-3 text-center-mobile">
<h5><a href="../latest/docs/" class="white">Documentation</a></h5>
<ul class="list-unstyled">
<li><a href="../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
<li><a href="../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
<li><a href="../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
<li><a href="../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../latest/examples/" class="white">Examples</a></h5>
<ul class="list-unstyled">
<li><a href="../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
<li><a href="../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
<li><a href="../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
<li><a href="../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../community/index.html" class="white">Community</a></h5>
<ul class="list-unstyled">
<li><a href="../community/contributors.html" class="regular light-white">Contributors</a></li>
<li><a href="../community/social.html" class="regular light-white">Social</a></li>
<li><a href="../community/sources.html" class="regular light-white">Sources</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../security/index.html" class="white">Security</a></h5>
<ul class="list-unstyled">
<li><a href="https://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
<li><a href="https://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
<li><a href="https://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="row bottom-footer text-center-mobile">
<div class="col-sm-12 light-white">
<p>Copyright &copy; 1999-2022 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</div>
</div>
</div>
</footer>
<!-- Holder for mobile navigation -->
<div class="mobile-nav">
<ul>
<li><a hef="../latest/docs/admin/index.html">Administrators</a>
<li><a hef="../latest/docs/developer/index.html">Developers</a>
<li><a hef="../latest/docs/advanced/index.html">Advanced</a>
<li><a hef="../community/index.html">Community</a>
</ul>
<a href="#" class="close-link"><i class="arrow_up"></i></a>
</div>
<!-- Scripts -->
<script src="../js/jquery-1.11.1.min.js"></script>
<script src="../js/owl.carousel.min.js"></script>
<script src="../js/bootstrap.min.js"></script>
<script src="../js/wow.min.js"></script>
<script src="../js/typewriter.js"></script>
<script src="../js/jquery.onepagenav.js"></script>
<script src="../js/tree.jquery.js"></script>
<script src="../js/highlight.pack.js"></script>
<script src="../js/main.js"></script>
</body>
</html>