notes/review/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
            "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Code Review Guidelines - comp.lang.javascript</title>
<link href="../../faq.css" rel="stylesheet" type="text/css">
<link href="../notes.css" rel="stylesheet" type="text/css">
</head>
<body>
<h1>Code Review Guidelines</h1>
<div id="faqNav">
  <a href="../../">FAQ</a> &gt; <a href="../">FAQ Notes</a>
</div>
<p>
  Article by Garrett Smith
</p>
<p>
Peer code review is where software developers review each others' 
development code.
</p>

<h2>Benefits</h2>
<p>
The number one benefit to code reviews is code quality. Code reviews make the code 
better. Here are some other benefits:
</p>

<ul>
    <li>
        Spreads understanding about the code being reviewed.
    </li>
    <li>
        Helps find bugs before they get to QA and avoids QA churn. 
    </li>
    <li>
        Helps identify potential problems, bad practices, or maldesign.
    </li>
    <li>
        Preparation for review will require the code author to check his 
        code against the <a href="../code-guidelines/">code guidelines</a> and
        clean it up (bugs fixed prior to review).
    </li>
    
    <li>
        Encourages collaboration.
    </li>

    <li>
        Keeps code cleaner and more maintainable.
    </li>
</ul>
<h2>How to perform the Review</h2>
<p>
Take your time understand the problem and how it is addressed in the solution. 
</p>

<p>
Focus on a small piece at a time. 
</p>

<p>
A code review should be objective and should state actual problems. 
Saying "the code is bad" is not a helpful review. Instead, explain 
the problem clearly. If the problem is severe, then say why.
</p>

<h2>Preparation of Reviewed Code</h2>
<p>
This section is for the the reviewee (the person whose code is being reviewed).
</p>

<p>
The reviewee should prepare for a code review by following the
the <a href="../code-guidelines/">code guidelines</a>. 
</p>

<h3>Posting Code for Review and Code Reviews</h3>
<p>
When posting code to the newsgroup, it is important to make sure 
to transmit it such that it can be easily read and understood.
</p>

<ul>
    <li>Format the code to 72 char width. </li>
    
    <li>Replace any spaces in the source code with tabs.</li>
    
    <li>Post small sections at a time. 
    <p>By focusing carefully on small 
    sections, the code review can find more bugs. The reviewer may want to 
    spend an hour reviewing the code, then come back to re-review his notes 
    and comments for another hour. 
    </p>
    </li>
</ul>

<h3>Rebuttals</h3>
<p>
The reveiwee may challenge a criticism and, if the challenge cannot be 
rebutted, the criticism shall be withdrawn.
</p>

</body>
</html>