Comments Suggestion

Topics: Developer Forum
Jan 24, 2007 at 11:45 AM
Would you mind if I pepper some comments around as I go through the source and learn what each bit does? It'll help everyone quickly see what does what :)

Also I'd suggest that when we comment we put "//AJ: This is a comment" where AJ is the developer initials so that if someone needs to ask a question they can find out who wrote the comment.
Coordinator
Jan 24, 2007 at 8:20 PM
Only really needs initials if you're using the comment to explain why you did something in the source, which may not appear logical just by looking at the code, like

//WS: I added this because using Something.SomethingElse() is faster than Thing.TheThing()

Other than that, i think it'd keep the code cleaner if stuff was just XML commented.

Also, on a similar topic....

You may have noticed I've begun to "regionize" the code. Regions are created to enclose members of a similar type and accessibility. The name of the region is in the format "<Type> - <Accessibility>", with plurals, for example, "Constructors - Public". Members inside the regions must be sorted alphabetically.
Jan 25, 2007 at 8:54 AM
I use

Enums

Events

Event Accessors
EventAccessorName

Fields

Properties
PropertyName

Constructors

Methods
MethodName
Abstracts
MethodName
Overrides
MethodName
Events
MethodName



Leaving out the ones that arn't used.
Jan 25, 2007 at 8:55 AM
Enums

Events

Event Accessors
-EventAccessorName

Fields

Properties
-PropertyName

Constructors

Methods
-MethodName
-Abstracts
--MethodName
-Overrides
--MethodName
-Events
--MethodName
Coordinator
Jan 30, 2007 at 7:24 PM
Personally I don't really like nested regions. Also, when you right click on the document in VS2k5 and do "Outlining - Collapse to definitions", its better than having one region for each method IMHO.

I have to dash to work at the moment but when I get back tonight I'll set down a "standard" for regionizing that we can all agree on :)
Coordinator
Jan 31, 2007 at 5:58 AM
Ok, here's my suggestion which I hope is adequate:

Region name is the member type first (alphabetical, plural), followed by a space-dash-space, followed by the access type (sorted least-accessible to most). If there are abstract members of that type and access, add another space-dash-space and "Abstract" to the region.

For example:
  • Constants - Public
  • Constructors - Private
  • Constructors - Internal
  • Methods - Public
  • Properties - Protected
  • Properties - Protected - Abstract
  • Properties - Public
  • Properties - Public - Abstract

Also, correct me if i'm wrong here but the access modifiers from least accessible to most accessible are:
  1. Private
  2. Internal
  3. Protected Internal
  4. Protected
  5. Public
Jan 31, 2007 at 3:57 PM
Private
Protected Internal
Protected
Internal
Public

Protected Internal is definatly less accessable than internal or protected. As for the order of internal and protected I'd say internal is more accessable but that might not be right.
Jan 31, 2007 at 4:02 PM
opps got it compleatly wrong hehe ;)

in the case of Protected Internal it's not Protected AND Internal it's Protected OR Internal.

Private
Protected
Internal
Protected Internal
Public

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1066067&SiteID=1
Coordinator
Jan 31, 2007 at 5:52 PM
Ok so basically protected internal is kind of worthless... Might as well just make it internal.

Looks like this is going to be the new order:
  • Private
  • Protected
  • Internal
  • Protected Internal
  • Public

Also, perhaps we should also set down a rule that nothing can be without an access modifier (as that is vague)?
Feb 1, 2007 at 2:16 PM
Yeah personally I always put an access modifier. Some dev's make the comment that if you dont know what the access is by default you shouldn't be coding. I make the point that why be ambiguious and risk mistakes when you can be clear about what you mean ;)

And Protected Internal isn't useless ... it's handy for things like data access layers where you only want something to be accessed by classes in the same assembly (the DAL assembly) and the inheriting objects (the business objects). But yeah it isn't useful in many situations.

As an interesting side note, Protected AND Internal is actually implimented in the CLR its just not implimented in c# (info from the link i posted in my earlier comment).