Documentation

Coordinator
Jul 10, 2008 at 11:36 PM
Edited Jul 14, 2008 at 4:16 AM
Hi all!

I wanted to update the progress I am making with the documentation. I was originally going to follow a CMMI-style management process in which I was going to create a standard procedure for just about every element within the project. Unfortunately the documentation is taking way to long to develop, so I am limiting the amount of effort I plan on putting into the SPs. The coding standard SP is fairly complete and is now available for download. I also uploaded SP 1-2 for process and samples on code peer review procedures. There are several references to other SPs I had planned to develop but will now put on the back burner in order to get the project moving. The final SP I have been working on is the SP 1-5 Software Development process document. It will define the project roles, and process that will be used to manage this project and is now online. All of these SPs should be considered "living documents" in such that they can change as needed.

Please let me know if you have any questions regarding these docs. I expect to be working on the Requirements Document next, and finish off a SDP by the end of the night.
Developer
Jul 12, 2008 at 9:04 AM
Looks like  a great project you are putting together and I would not mind being involved. Here is a few comments regarding your coding practices document.

4.4.1 Private Properties

a. Private property (member) variables should be mixed case, using a hybrid of Hungarian and UpperCamelCase conventions.

b. Avoid abbreviations, one-character names, and non-alphanumeric characters like the underscore "_".

c. Should be prefixed with the character "p" to denote the private nature of the member variable. The next prefixed character should be one of the following characters to delineate the variable type:


My Comment: I personally do not like this approach as with IDE being what it is today you no longer need identifiers to tell you the scope or type of variable you are dealing with and the added hungarian notation makes it less readable. 



 

4.5 Localized Variables

 

a. Variable names that are local to a code block should be named using either Systems or Applications Hungarian notation and should not start with an underscore.

b. The choice of variable name should be mnemonic; this is, designed to indicate to the casual observer the intent of its use.

c. One-character variable names should be avoided, except for local variables serving as an index in a for-loop or used within a few lines of code for temporary and obvious use.

d. Names should be mixed case using a lowerCamelCase naming convention.

 

My Comment: Should not use hungarian notation.

 

4.6 Constants

 

Constants should be named in all uppercase letters, with words separated by underscore "_" characters. The following naming format provides the most detail within a constant:

Module_Type_ValueMeaning.


My Comment: Having used FXCop this naming convention is not recommended any longer and should simply use CamelCase.



Additional Comment: Probably implied but since you are so good at detailing your expectations I would add something stating that member variables should not be public and all public access requires a public property.

 

Coordinator
Jul 14, 2008 at 4:19 AM

Thanks so much for your input. I have been wrestling with the naming conventions, sometimes it's hard to shake the past. I would like to know what is the suggested naming method for private property field values that will be exposed through a public property? I've seen m_NameHere to denote it's member status, and I've seen _NameHere to denote it's private nature. I've also seen nameHere as well. I'm running C# Analyizer right now to clean up some of the code even further.

Thanks,

Rob

Developer
Jul 14, 2008 at 3:22 PM
private fields should be pascalCase and should not have any prefix on it.

Preferred:

firstName

Not Preferred:

_firstName
m_firstName
strFirstName
sFirstName


I used to use Hungarian notation and found it was no longer suggested a few years ago and started randomly using FXCop on my code and changing over its suggestions. I struggled a bit at first but as time went on I found myself adjusting and now find it favorable and find code writting with prefixes harder to read. The key is naming your variables well so they are self documenting as to what they are and the beauty of VS is that you can simply hover over anything and see what it is.

Also if I reference a member field in a method I use this.firstName to quickly show me that the field being referenced is a member field.


Coordinator
Jul 14, 2008 at 6:29 PM
Agreed. I was reading up on the latest best practices on the MSDN site and came to the same conclusions. I'll make an update to the document and get the revision posted ASAP.

Thanks,
Rob

I'll be releasing the serverLib and SMTP test projects here soon since they are closest to being complete. I just need to go through them via c# analyzer a bit more.
Coordinator
Jul 14, 2008 at 9:39 PM
SP 1-1 Coding Standards is now rev 16, with changes made to class constant, property and method naming conventions.

Thanks,

Rob
Developer
Jul 15, 2008 at 12:45 AM

Correction on my previous comment.  Private Fields should be camelCase not PascalCase. I always get that backwards.

Pascal - In Pascal casing the first letter of each word in an identifier is capitalized. For example BackColor
 
Camel - In Camel casing only the first letter of the second, third, etc.. word in a name is capitalized; for example, backColor

 

 

Coordinator
Jul 15, 2008 at 7:50 PM
I always get those backwards as well so I adopted "lowerCamelCase" and "UpperCamelCase" nomenclature to alleviate any misinterpretations I or others may have.

-Rob
Coordinator
Jul 15, 2008 at 10:34 PM
Update

I've uploaded a new document called the Master Resource Reference. Within this PDF, you will find a list of useful links to documentation on protocols and other RFCs, ISO standards, and specifications.

This will give developers a central master reference to get access to the standards that will be utilized in one form or another within this project.

-Rob
Developer
Jul 17, 2008 at 5:06 AM
<style> </style>
Rob sent this to your email address listed in the document but got no response so posting.

1) Fixup all your examples to reflect not using prefix or hungarian notation
 
2) 4.4.1 change text from lowerCamelCase or camelCase as this convention is called camelCase
 
3) 4.4.2 Change UpperCamelCase to PascalCase as it is implied.
 
4) 4.4.3 UowerCamelCase typo ;-) and should be PascalCase.
 
5) 4.5 lowerCamelCase should change to camelCase
 
Might also be worth defining Pascal and Camel casing.
 
Pascal - In Pascal casing the first letter of each word in an indentifier is capatalized. For example BackColor
 
Camel - In Camel casing only hte first letter of the second, third, etc.. word in a name is capitalized; for example, backColor
 
Two-Letter abbreviations in Pascal casing have both letters capitalized. In Camel casing this also holds true, except at teh start of an identifier where both letters are writting in lower case.With respect to capitalization in Pascal and Camel casing, abbreviations with more than two letters are treated as ordinary words.
 
 
Camel
NewImage
UIEntry
 
Pascal
newImage
uiEntry
 
If you wanted I would be happy to update your document and send it back to you if that will take that off your plate so you can finish the code.
Coordinator
Jul 17, 2008 at 5:59 AM
Edited Jul 17, 2008 at 5:59 AM
Shoot me another e-mail; it may have been eaten up by the spam filter or Outlook.

Documentation is written in Word 2007; I "Save As" to PDF for publishing.

I can send you the latest revisions if you shoot me an e-mail or CC me to cyberrob410 (at) yahoo (dot) com.
Thanks,

Rob