Difference between revisions of "SoftwareStandards"

From BU Computer Science
Jump to navigation Jump to search
(Created page with "=Software Standards= ==Overview== # Overall, the simpler the code, the better. Writing a complex statement is usually not the best way to code. Writing two or three simple s...")
 
m (Documentation)
Line 5: Line 5:
 
# In most cases, a more readable code is preferred to code that optimizes at the statement level.  This optimization can almost always be achieved by the compiler/interpreter.  Therefore its benefit is minimal at the coding level.  Readablity is essential for good code
 
# In most cases, a more readable code is preferred to code that optimizes at the statement level.  This optimization can almost always be achieved by the compiler/interpreter.  Therefore its benefit is minimal at the coding level.  Readablity is essential for good code
 
==Documentation==
 
==Documentation==
 +
 
A properly documented software project includes the following:
 
A properly documented software project includes the following:
# Each source code file includes a header comment that includes:<br>/********************************************************<br>* Author:<pre>  author name</pre><br>
+
<ol>
Course: course code (i.e. CSC 121)
+
<li>Each source code file includes a header comment that includes:<br><pre>
Assignment: assignment name
+
        /********************************************************
********************************************************/
+
        * Author:>  author name>
a. If the file is the main file, then the header should also include (before the ending stars) :
+
* Course: course code (i.e. CSC 121)
Problem: short problem description
+
* Assignment: assignment name
b. Else it should include (before the ending stars):
+
********************************************************/</pre>
Purpose: short description as to the purpose of that file
+
<ol type="a">
2. Each variable that is not self-evident to an independent reader should have a comment indicating its purpose.
+
<li>If the file is the main file, then the header should also include (before the ending stars) :<pre>
3. Each method that is non-trivial must have a single simple sentence stating its purpose.  Trivial methods are defined as one line methods, or extremely obvious to the independent reader.
+
* Problem: short problem description</pre>
4. Any complex section of code, must have a comment explaining the logic
+
<li>Else it should include (before the ending stars):<pre>
 
+
* Purpose: short description as to the purpose of that file</pre>
Style requirements
+
</ol>
1. No line should exceed 80 characters long unless absolutely necessary.  This is to facilitate simple printing and easy of reading the code in most environments.
+
<li>Each variable that is not self-evident to an independent reader should have a comment indicating its purpose.
2. Soft tabs (not hard tabs) should be used to accurately allow for proper indentation in any environment.
+
<li> Each method that is non-trivial must have a single simple sentence stating its purpose.  Trivial methods are defined as one line methods, or extremely obvious to the independent reader.
3. Indentation that indicated level should be 4 spaces.  Spacing used to line up arguments or to make long lines readable can be more.
+
<li> Any complex section of code, must have a comment explaining the logic
4. No method/function (including comments) should be more than 66 lines long (except in extreme cases).  This is to encourage proper modularilty of code.
+
</ol>
5. White space should be used increase readability.
+
==Style Requirements==
6. Field variables should only be used to store information between method calls.
+
<li>No line should exceed 80 characters long unless absolutely necessary.  This is to facilitate simple printing and easy of reading the code in most environments.
7. Constants should be names entirely with uppercase letters and numbers
+
<li>Soft tabs (not hard tabs) should be used to accurately allow for proper indentation in any environment.
8. Class names must start with an uppercase letter and contain at least one lower case letter.
+
<li>Indentation that indicated level should be 4 spaces.  Spacing used to line up arguments or to make long lines readable can be more.
9. Variables and method/function numbers must start with a lowercase letter
+
<li>No method/function (including comments) should be more than 66 lines long (except in extreme cases).  This is to encourage proper modularilty of code.
10. Field variables should be labeled as private unless there is a specific reason to use another label.   
+
<li>White space should be used increase readability.
11. Methods should be labeled public unless there is a good reason not to.
+
<li>Field variables should only be used to store information between method calls.
12. Only class constants should be accessible without using a access method outside of the class.
+
<li>Constants should be names entirely with uppercase letters and numbers
13. A class should contain the following by default:
+
<li>Class names must start with an uppercase letter and contain at least one lower case letter.
a. At least one constructor
+
<li>Variables and method/function numbers must start with a lowercase letter
b. An accessor for each field variable
+
<li>Field variables should be labeled as private unless there is a specific reason to use another label.   
c. A modifier for each field variable that is allowed to change
+
<li>Methods should be labeled public unless there is a good reason not to.
d. Standard methods including:  toString, equals, and possible compareTo
+
<li>Only class constants should be accessible without using a access method outside of the class.
14. Field variables should only be initialized in constructors, never where declared.
+
<li> A class should contain the following by default:
15. While learning to program, no variable should be initialized in the same statement it is declared.
+
<ol type="a">
16. It should be extremely rare to declare variables inside a loop.  Whenever possible, they should be declared outside of the loop and then reused inside.
+
<li>At least one constructor
17. Exiting a loop via a break should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
+
<li>An accessor for each field variable
18. Exiting a loop via a return should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
+
<li>A modifier for each field variable that is allowed to change
19. For loops should only be used in count controlled loops.
+
<li>Standard methods including:  toString, equals, and possible compareTo
20. ()’s should be used in complex boolean expressions (or arithmetic expressions) to increase readability even if they are not needed.
+
</ol>
 +
<li>Field variables should only be initialized in constructors, never where declared.
 +
<li>While learning to program, no variable should be initialized in the same statement it is declared.
 +
<li>It should be extremely rare to declare variables inside a loop.  Whenever possible, they should be declared outside of the loop and then reused inside.
 +
<li>Exiting a loop via a break should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
 +
<li>Exiting a loop via a return should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
 +
<li>For loops should only be used in count controlled loops.
 +
<li>()’s should be used in complex boolean expressions (or arithmetic expressions) to increase readability even if they are not needed.

Revision as of 16:28, 23 December 2020

Software Standards

Overview

  1. Overall, the simpler the code, the better. Writing a complex statement is usually not the best way to code. Writing two or three simple statements instead is much better.
  2. Avoiding defaults is preferred. It saves little. Stating it instead of assuming it makes it explicit and easier for the next developer. In addition, defaults may vary based on the language. Developing a dependence on them is not good.
  3. In most cases, a more readable code is preferred to code that optimizes at the statement level. This optimization can almost always be achieved by the compiler/interpreter. Therefore its benefit is minimal at the coding level. Readablity is essential for good code

Documentation

A properly documented software project includes the following:

  1. Each source code file includes a header comment that includes:
            /********************************************************
             * Author:>  	author name>
    	 * Course:	course code (i.e. CSC 121)
    	 * Assignment:	assignment name
    	********************************************************/
    1. If the file is the main file, then the header should also include (before the ending stars) :
      	 * Problem:	short problem description
    2. Else it should include (before the ending stars):
      	 * Purpose:	short description as to the purpose of that file
  2. Each variable that is not self-evident to an independent reader should have a comment indicating its purpose.
  3. Each method that is non-trivial must have a single simple sentence stating its purpose. Trivial methods are defined as one line methods, or extremely obvious to the independent reader.
  4. Any complex section of code, must have a comment explaining the logic

Style Requirements

  • No line should exceed 80 characters long unless absolutely necessary. This is to facilitate simple printing and easy of reading the code in most environments.
  • Soft tabs (not hard tabs) should be used to accurately allow for proper indentation in any environment.
  • Indentation that indicated level should be 4 spaces. Spacing used to line up arguments or to make long lines readable can be more.
  • No method/function (including comments) should be more than 66 lines long (except in extreme cases). This is to encourage proper modularilty of code.
  • White space should be used increase readability.
  • Field variables should only be used to store information between method calls.
  • Constants should be names entirely with uppercase letters and numbers
  • Class names must start with an uppercase letter and contain at least one lower case letter.
  • Variables and method/function numbers must start with a lowercase letter
  • Field variables should be labeled as private unless there is a specific reason to use another label.
  • Methods should be labeled public unless there is a good reason not to.
  • Only class constants should be accessible without using a access method outside of the class.
  • A class should contain the following by default:
    1. At least one constructor
    2. An accessor for each field variable
    3. A modifier for each field variable that is allowed to change
    4. Standard methods including: toString, equals, and possible compareTo
  • Field variables should only be initialized in constructors, never where declared.
  • While learning to program, no variable should be initialized in the same statement it is declared.
  • It should be extremely rare to declare variables inside a loop. Whenever possible, they should be declared outside of the loop and then reused inside.
  • Exiting a loop via a break should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
  • Exiting a loop via a return should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.
  • For loops should only be used in count controlled loops.
  • ()’s should be used in complex boolean expressions (or arithmetic expressions) to increase readability even if they are not needed.