blob: 5c15abbbd4f45c3e9f660c4d46e603c6b78910ac [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Coding standards</title>
<link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
</head>
<body>
<a href="http://github.com/apache/struts" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
</a>
<header>
<nav>
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
Menu
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
</div>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li>
<li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
</ul>
</li>
<li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li>
</ul>
</div>
</div>
</div>
</nav>
</header>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/coding-standards.md" title="Edit this page on GitHub">Edit on GitHub</a>
<h1 class="no_toc" id="coding-standards">Coding standards</h1>
<ul id="markdown-toc">
<li><a href="#in-the-first-place" id="markdown-toc-in-the-first-place">In the first place</a></li>
<li><a href="#separation-of-concern" id="markdown-toc-separation-of-concern">Separation of concern</a></li>
<li><a href="#ask" id="markdown-toc-ask">Ask!</a></li>
<li><a href="#wip" id="markdown-toc-wip">WIP</a></li>
<li><a href="#examples" id="markdown-toc-examples">Examples</a> <ul>
<li><a href="#from-defaults-to-extractions" id="markdown-toc-from-defaults-to-extractions">From defaults to extractions</a></li>
</ul>
</li>
</ul>
<h2 id="in-the-first-place">In the first place</h2>
<p>Please remember that most of the time others will read your code. Focusing on that allow you to gain required perspective
about how code should look like. Defaults, margins, convention doesn’t matter if what you write is hard to read.</p>
<p><strong>Readability is the first rule!</strong></p>
<h2 id="separation-of-concern">Separation of concern</h2>
<p>If you want to reformat given file, part of class, etc do it in a dedicated commit. Never ever mix bug fixing,
new feature implementation with code reformatting. Thus only confuses people reviewing your code.</p>
<p><strong>Reformat different than coding!</strong></p>
<h2 id="ask">Ask!</h2>
<p>If something isn’t clear, you have doubts and anything else - ask! Maybe during materialising your thoughts as text
you will gain the answer - Rubber Duck effect :-) Anyway, instead spending time on looking for solution - ask.</p>
<p>The best place to ask question is Struts Developers List <a href="mailto:dev@struts.apache.org">dev@struts.apache.org</a></p>
<h2 id="wip">WIP</h2>
<p>If you have any idea how to improve this guideline, don’t hesitate to send them to us! Any help is welcome!</p>
<h1 id="examples">Examples</h1>
<p>Below examples shows how you should proceed when adjusting given part of source code via reformatting, extracting
or improving.</p>
<h2 id="from-defaults-to-extractions">From defaults to extractions</h2>
<p>The original source code:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// Hidden input section
a = new Attributes();
a.add("type", "hidden")
.add("id", "__multiselect_" + StringUtils.defaultString(StringEscapeUtils.escapeHtml4(id)))
.add("name", "__multiselect_" + StringUtils.defaultString(StringEscapeUtils.escapeHtml4(name)))
.add("value", "").addIfTrue("disabled", disabled);
start("input", a);
end("input");
</code></pre></div></div>
<p>After applying default reformatting (80 columns margin):</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// Hidden input section
a = new Attributes();
a.add("type", "hidden")
.add("id",
"__multiselect_"
+ StringUtils
.defaultString(StringEscapeUtils
.escapeHtml4(id)))
.add("name",
"__multiselect_"
+ StringUtils
.defaultString(StringEscapeUtils
.escapeHtml4(name)))
.add("value", "").addIfTrue("disabled", disabled);
start("input", a);
end("input");
</code></pre></div></div>
<p>Some suggestions how to improve the code:</p>
<ul>
<li>
<p>use static imports</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> a.add("type", "hidden")
.add("id", "__multiselect_" + defaultString(escapeHtml4(id)));
</code></pre></div> </div>
</li>
<li>
<p>use dedicated method</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> a.add("type", "hidden")
.add("id", "__multiselect_" + safeId(id));
</code></pre></div> </div>
</li>
<li>
<p>use builder</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> a.add("type", "hidden")
.add("id", HtmlID.with("__multiselect_").withSafeId(id).create());
</code></pre></div> </div>
</li>
</ul>
<p>As you can see, reformatting a code is just the beginning, you shouldn’t stop there and think <em>how can I improve
readability</em> and follow that path to the end.</p>
</section>
</article>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="http://www.apache.org/">The Apache Software Foundation </a>.
All Rights Reserved.
</div>
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
</div>
<div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div>
</footer>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s);
js.id = id;
js.src = "//platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js, fjs);
}
}(document, "script", "twitter-wjs");</script>
<script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s);
js.id = id;
js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
</body>
</html>