Superior coding techniques and programming practices are hallmarks of a professional programmer. The bulk of programming consists of making a large number of small choices while attempting to solve a larger set of problems. How wisely those choices are made depends largely upon the programmer's skill and expertise.
This document addresses some fundamental coding techniques and provides a collection of coding practices from which to learn. The coding techniques are primarily those that improve the readability and maintainability of code, whereas the programming practices are mostly performance enhancements.
The readability of source code has a direct impact on how well a developer comprehends a software system. Code maintainability refers to how easily that software system can be changed to add new features, modify existing features, fix bugs, or improve performance. Although readability and maintainability are the result of many factors, one particular facet of software development upon which all developers have an influence is coding technique. The easiest method to ensure that a team of developers will yield quality code is to establish a coding standard, which is then enforced at routine code reviews.
g_for global variables and
m_for module-level variables in Microsoft Visual Basic®.
NUM_DAYS_IN_WEEK. Also, begin groups of enumerated types with a common prefix, such as
- When naming tables, express the name in the singular form. For example, use
- When naming columns of tables, do not repeat the table name; for example, avoid having a field called
EmployeeLastNamein a table called
- Do not incorporate the data type in the name of a column. This will reduce the amount of work needed should it become necessary to change the data type later.
Microsoft SQL Server
- Do not prefix stored procedures with
sp_, because this prefix is reserved for identifying system-stored procedures.
- In Transact-SQL, do not prefix variables with
@@, which should be reserved for truly global variables such as
- Minimize the use of abbreviations. If abbreviations are used, be consistent in their use. An abbreviation should have only one meaning and likewise, each abbreviated word should have only one abbreviation. For example, if using min to abbreviateminimum, do so everywhere and do not later use it to abbreviate minute.
- When naming functions, include a description of the value being returned, such as
- File and folder names, like procedure names, should accurately describe what purpose they serve.
- Avoid reusing names for different elements, such as a routine called
ProcessSales()and a variable called
- Avoid homonyms when naming elements to prevent confusion during code reviews, such as write and right.
- When naming elements, avoid using commonly misspelled words. Also, be aware of differences that exist between American and British English, such as color/colour and check/cheque.
- Avoid using typographical marks to identify data types, such as $ for strings or % for integers.
Software documentation exists in two forms, external and internal. External documentation is maintained outside of the source code, such as specifications, help files, and design documents. Internal documentation is composed of comments that developers write within the source code at development time.
One of the challenges of software documentation is ensuring that the comments are maintained and updated in parallel with the source code. Although properly commenting source code serves no purpose at run time, it is invaluable to a developer who must maintain a particularly intricate or cumbersome piece of software.
Following are recommended commenting techniques:
- When modifying code, always keep the commenting around it up to date.
- At the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routine's purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction to understand why the routine exists and what it can do.
- Avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. However, end-line comments are appropriate when annotating variable declarations. In this case, align all end-line comments at a common tab stop.
- Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.
- Avoid surrounding a block comment with a typographical frame. It may look attractive, but it is difficult to maintain.
- Prior to deployment, remove all temporary or extraneous comments to avoid confusion during future maintenance work.
- If you need comments to explain a complex section of code, examine the code to determine if you should rewrite it. If at all possible, do not document bad code—rewrite it. Although performance should not typically be sacrificed to make the code simpler for human consumption, a balance must be maintained between performance and maintainability.
- Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.
- Comment as you code, because most likely there won't be time to do it later. Also, should you get a chance to revisit code you've written, that which is obvious today probably won't be obvious six weeks from now.
- Avoid the use of superfluous or inappropriate comments, such as humorous sidebar remarks.
- Use comments to explain the intent of the code. They should not serve as inline translations of the code.
- Comment anything that is not readily obvious in the code.
- To prevent recurring problems, always use comments on bug fixes and work-around code, especially in a team environment.
- Use comments on code that consists of loops and logic branches. These are key areas that will assist the reader when reading source code.
- Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.
- Throughout the application, construct comments using a uniform style, with consistent punctuation and structure.
NotesDespite the availability of external documentation, source code listings should be able to stand on their own because hard-copy documentation can be misplaced.
External documentation should consist of specifications, design documents, change requests, bug history, and the coding standard that was used.
Content will be erased after question is completed.