This chapter introduces general rules applicable to
several technologies covered in this document. Technology specific information is
provided in the next chapters.
Proper documentation is the prerequisite for future
code maintenance. As much documentation as possible should be included in the
source code. Additional documents tend to be neglected during upgrades and bug
fixes.
Files headers should include titles, descriptions
and copy rights. The change history should not be included, because this can be
very cumbersome and is often not up-to-date. The versioning tool can provide
this information more accurately and more detailed.
The following formatting rules apply universally,
independently which technology is used (C#, HTML, Stored Procedure, etc.). A
good general overview provides the MSDN Library:
.NET Development - Visual Studio .NET. Product Documentation
- Developing with Visual Studio .NET - Working with Code, HTML, and Resource
Files - Coding Techniques and Programming Practices - Coding Techniques.
General rules:
•
Use lower case characters for keywords
•
Use 4 spaces for tabs
•
Use a space after but not before??挔 ?挔 ??/p>
•
Don抰 use spaces before and after ??if the period is used to
connect two entities (object.property).
•
Use one space before and after binary operators like ????????
In complicate formulas, spaces might be uses to show which calculation is
performed first: a*b + c*d
or (a+b) * (c+d)
•
Use a space before and after an equal sign for assignments: variable = 5, but no spaces for
comparisons: if variable=5 then ?/code>.
An example for an assignment to a Boolean variable and comparison in the same
statement: BooleanFlag = a=b
Technology specific formatting rules are covered in:
4.5.1 Formatting Rules for C#
7.1 Formatting Rules for HTML
8.7 Formatting Rules CSS
10.3.1 Formatting Rules for SQL Stored Procedures
A naming convention makes code easier to understand
and maintain by a group of developers. Use Microsoft抯 Naming Guidelines in MSDN
Library - .NET Development - .NET Framework ?Reference - Design Guidelines for
Class Library Developers - Naming Guidelines.
For your convenience, I repeat here the most
important once:
•
Use Pascal style capitalization (FirstLetterCapital) for most names, except parameters,
where camel casing (firstLetterSmall)
should be used.
•
Do not use names which differentiate only in capitalization, even
not in C#, which would distinguish between these names. It抯 just too
confusing.
•
Do not use the underscore character (_), except to mark private fields in classes or to separate to
abbreviations: TextHTML_UTF8 ?/p>
•
Do not use Hungarian notation prefix: lblFamilyName. Microsoft
recommends not to include type information in names, because the IDE can
provide this information if needed. However, it seems that programs are
sometimes more readable, like. This: FamilyNameLabel, FamilyNameValue
This shows clearly that the objects are about a family name, but also
differentiates between different elements used to handle a family name.
•
Do use the underscore character (_),?to mark private fields in
classes
•
Don抰 use just capital letters for abbreviations:
Bad: PBDBException,
Better: PBoxDBException
Bad: TextHTMLUTF8,
Better: TextHTML_UTF8?or TextHtmlUtf8
Use abbreviations sparingly and consistently. In
.NET, there are thousands of objects and it would be hard to find unique
abbreviations for all of them and to remember them. Commonly used abbreviations
should be listed in this document.
•
Code review
- Proper
documentation
- Are
there enough and understandable comments ? Do the comments correspond with the
actual code (sometimes code gets changed, but not the comments)
- Are
all parameters tested against missing (null) or illegal values ?
- Proper
exception handling
- Checking
for completeness of test procedures
•
Single stepping through test procedures
If more than one person works on a project, source
code control software like Visual SourceSafe is needed.
The development workstations are used for writing source
code and to test it. For ASP.Net development, it runs also IIS locally to allow
easy debugging of code under development.
•
MSDN Universal Subscription for:
- Windows
XP
- Office
XP
- Visual
Studio .NET
- Visual
SourceSafe
- Visio
- Project
- All
development server licenses
•
Photoshop for Web Developers
•
Pentium PC, 512 MByte RAM, 19 inch Monitor
Additional PCs are needed for testing of website
with different browsers (ASP.NET), installation and rollout tests (non ASP.NET)
and for stress testing (load simulation). They have the same setup as
development PCs, maybe less powerful hardware. No software licenses needed
(included in MSDN subscription).?
Provides each developer with his own test database
and a databases for integration, upgrade testing, etc. No software licenses
needed (included in MSDN subscription).
No software licenses needed (included in MSDN
subscription). This server is used for integration test, user acceptance test
and release test.
Chapters Overview