IT Web and Software Developer Software Development Standards

Transcription

1 IT Web and Software Developer Software Development Standards Definition of terms Identifier An identifier is the name you give variables, methods, classes, packages, interfaces and named constants. Pascal case Use uppercase letters for the first letter in the identifier and the first letter of each subsequent. BackColor, DataSet Camel case Use lowercase letters for the first letter of the identifier. Use uppercase letters for the first letter of each subsequent word. numberofdays, isvalid Uppercase Capitalize all letters in the identifier. HEADING, RED NOTE: This convention is ONLY used for named constants and enumerated types. Hungarian notation The name of the variable or function indicates its type or intended use. strfirstname NOTE: Hungarian notation is NOT used in Java. Commenting Code Contrary to popular belief, code is not self-documenting; using descriptive variable, class, and method names is desirable; however, it is no substitute for commenting your code. In general, you want to describe the why not just the what. Describing why, allows you and subsequent programmers to determine the thought process that went into creating the code. Depending on the programming language you are using, the symbols for commenting code can differ. Comments can be: Inline Block Used to identify matching curly brackets Include your name, assignment name, and date created Naming Conventions General naming conventions: Do not use Hungarian notation. Do not declare an object (custom or intrinsic) with a prefix such as o, ob, or obj. Spell words out. Avoid abbreviations. Single letter variable names are not allowed EXCEPT as an iterator (loop control) variable in countercontrolled loops: (for int i = 0; ) The variable sb is common and acceptable for identifying a StringBuilder class. Only use acronyms if everyone knows what they represent and the meaning is not ambiguous. Most of us know SSN means Social Security Number, but what does PID mean? Identifiers should be less than 30 characters. Change names generated by tools to something more meaningful (jtextfield1 to textfieldname). Do not qualify variables with a number suffix (name1, name2, name3). Use an array, array list or collection. Do not repeat the name of the container in the name of the contained. For example, the first name field in a Person class is firstname, not personfirstname.

2 Variable Names: Use camel case. Be descriptive. Use a noun or noun phrase. o Good Examples: firstname, lastname, numberofrecords o Bad Examples: ln, fn, eof Note: Single letter variable names (i, j, k, l) may be used for counter loops. It is common and acceptable to use sb as the variable name for the StringBuilder class. Named Constants and Enumerated Types: Use all uppercase letters. Be descriptive. Use a noun or noun phrase. Separate the noun phrase with an underscore o Good SALES_TAX o Bad SALESTAX Note: The underscore makes the named constant variable easier to read. Boolean Variable Names: Identifiers should reflect the variable s Boolean-ness. Use is, has, or can as the leading verb. Reflect a positive or optimistic result. o Good Boolean issuccessful = false; o Bad Boolean isnotsuccessful = true; Component Names: Camel case the component name to the end your variable name. This seems long, but you will appreciate the clarity when like components are listed together in your development environment. Name each component to reflect contents or purpose of the component. This practice is very helpful to people who rely on screen readers. Some common controls are listed below. Component TextField (Java) Textbox (.Net) Combo Box Button Checkbox Radio button Java Example textfieldfirstname comboboxcountry buttonsubmit checkboxbarrier radiobuttoncartype Class Names: Use Pascal case. Be descriptive. Use a noun or noun phrase. Method Names: Use Camel case in Java and JavaScript. Be descriptive but not too specific. o Good getcustomer( ) o Bad getcustomertim( ) Lead with verb. The format of the method name should be ActionVerb + Subject + optional returnedsubject public void setplayername(string playername) { this.playername = playername;

3 public String getplayername( ) { return this.playername; Style Considerations Indention: Indention and spacing makes code more readable. Consistency in indentations can be achieved easily by using the TAB key instead of spaces. Additionally, many development environments give you a set of key strokes that we auto-format your code after you write the code. Curly Braces: In Java, JavaScript, and C#, blocks of code are grouped together using curly braces {. Believe it or not, there is an on-going heated debate on the proper positioning of curly braces. Your main takeaway should be usage and consistency. Make sure you use curly braces and be consistent in your placement of them. Following are some common placement options. Option one: private void validateform( ) { if (condition is true) { else { different Option Two: private void validateform( ) { if (condition is true) { else{ different Option Three: private void validateform( ) { if (condition is true) { else{ different

4 The Exception to the Rule: Remember, usage and consistency are the key takeaways, however, there is one exception JavaScript, which you will learn in Advanced Web. JavaScript performs something called semi-colon insertion. That means if the JavaScript parser thinks you forgot a semi-colon at the end of a line, it will virtually insert it for you. Although you may think this is cool, it actually can be problematic and cause your code to behavior unexpectedly. Therefore, currently in JavaScript, it is essential to put the opening curly braces on the same line as your code. Since most languages do not care about curly brace placement, in my opinion, it s best to adopt either option two or three. That way you don t need to change your habits for one language. Variable Declaration: Declare variables at the top of the method. Use one line per variable. Initialize local variables at declaration. For safer programming, member variables should not be public. Keep them private and expose them by using public/protected Properties. Long Code Expressions: Lines of code that require you to scroll across the page should be broken into multiple lines (after a comma or operator) for readability. Indent subsequent lines of code. System.out.println("Controller: filldropdownlists: " + Arrays.toString(ex.getStackTrace())); Classes and Methods: Split lengthy code files into multiple classes. Lengthy methods that do more than one primary thing are hard to read and maintain. Re-factor long or multi-functional method into additional methods. Explicitly using access modifiers makes your code more readable. private void saveresults() Instead of void savereuslts() Note: Languages often have a default accessiblity level when one is not provided. In Java, the default (no modifier) allows for different accessibility than using a modifier. Use public methods sparingly. Do not put database calls in public methods. A better way is to have the public method call a private or internal method. If a method returns an object, it should return that object and not a null value. For instance, it s better to return an empty collection, rather than null. Plan for re-usability. [ Continued on next page ]

5 Enumerated Types: Using enumerated types (enums) enhances the clarity and readability of your code. Use them to document parameters and conditional paths. Please note, below is one type of enum, however, there are others. public enum SortDirection{ ASCENDING, DESCENDING Using an enum in code: switch(mysortdirection) { case(sortdirection. ASCENDING): //do stuff; break; case(sortdirection. DESCENDING): //do stuff; break; default: //do the default thing; break; Safe Programming Considerations Conditional Code Blocks and Event Handlers: Always end switch statements with a default path. Conceptually, this is the same as the next bullet point. Watch for unexpected values when using an if statement. If there are two possible values, never assume that if one is not matching then the only possiblity is the other value. if(mysortdirection == SortDirection. ASCENDING) { else if (mysortdirection == SortDirection. DESCENDING) { else else{ to indicate the unexpected happened Event handlers, such as button click events, should not contain executing code, they should instead, call a method that will execute the code. Error Handling and Try/Catch/Finally and Try with Resources (TWR): When logging exceptions in Java, capture exceptionvariable.getstacktrace(). Often, this information is priceless for troubleshooting your code. Structure the try/catch to just throw, not throw e. This will preserve the stack trace. Use key/value pairs to stash any idenifying information you may need to help troubleshoot the error condition. Try/Catch/Finally blocks are not needed in every method. Meaning try this, if it doesn t work, catch the error, but always run the finally code. In some cases the finally code is optional, especially since Java now has TWR. In Java SE 7 or above, use try with resources; this will automatically close or deallocate resources. It is especially important to use TWR when connecting to a database.

6 Accessing Databases / System Architecture: Use the Model View Controller (MVC) desgin pattern for separating business logic from the user interface. Never access a database directly from a user interface. Database input/output (IO) should be performed in the database package. To avoid SQL injection attacks, always validate user input prior to sending the data to the database. Return Statements: Use a variable to represent your returned value. If the requirements dictate, conditionally set the value of your variable. Return the value from one location within the code block. private boolean isvalidnumber(string input) { double number; boolean isvalid = false; try { number = Double.parseDouble(input); isvalid = true; catch (Exception e){ isvalid = false; return isvalid;