My project manager last week hinted at using ndoc on properties within a class. Is this something that should be done? Is it considered best practice to do this or not? I am currently expanding all my ndoc for the section of a project that I am working on but do not know how deep I need to go with it. I have of course provided summaries, params, returns and remarks to the class and each method but do properties require ndoc too?
Public properties are a contract to the outside world I think they should be documented.
Internal properties will only be used in the same assembly so you could get away with not documenting them.
Protected properties will only be used in derived classes (internal or public) so they might be in need of some documentation.
Private properties will only be used in the class itself so, again, you could get away with it.
Note that "getting away with not documenting it" suggests the way I feel about this: you should document. At the same time I realize that sometimes you need to do one thing or the other...
Perhaps you should ask this on http://programmers.stackexchange.com
Just like any other members, the meaning of properties should be documented. This should include not only what the property does or what it can be used for, but also its initial value, special cases (e.g. values that must not be assigned; values that would cause an exception or automatically be replaced with other values), as well as possibly the ramifications and purpose of overriding the property in a derived class where this is possible.
Public properties should definitely always be documented, whether your chosen documentation workflow uses GhostDoc, NDoc, or whatever. XML comments on public properties and methods show up in Intellisence when people use it, so there's no reason to not add something there. Even if the name of the property explains what it does, it's very nice to have XML comments there to confirm that. There are plenty of gotchas in plenty of code, so it's courteous to let the people who use your code know they're not walking into one.
Private properties can go either way. I'd hesitate to call it a particular best practice since to see the comments you have to be in the class, at which point you can just look at its usage trivially. That said, I still put XML comments on private properties, if for nobody else then for myself. There's no way you will remember what you were doing 6 months from now and any structural comments you can add will make it easier to pick up where you left off.
Related
If I'm dealing with one class and one public struct (not nested), Should I create a separate .cs just for the struct? Or leave it un-nested in its .cs file of the class? (This is assuming the struct relates to the class, but isn't so exclusive to the class that it should be nested and declared private)
Edit: I removed my initial question about two classes because I found C# classes in separate files?
Note that the only person(s) that can accurately answer this question is you, and your team. If your team is happy to find several related types inside a single file, combined due to ... whatever... then what I, or whomever other person, says, should be just ... irrelevant.
In any case, I would turn the question upside down:
Is there any reason to place two separate types (related by names, functionality, or whatever, but separate nonetheless) in the same file
and I've yet to come up with a good reason.
There are extensions/addins to Visual Studio where you can type in the name, and quickly navigate to the file, and I can think of three, but there are undoubtedly others:
DPack
ReSharper
CodeRush/Refactor! Pro
The first allows you to quickly navigate to a file by name. If you know the type, but have people putting multiple types into the same type, this will not be helpful, at all.
The second and third, lets you navigate to a type by name, but you shouldn't rely on people having those, or knowing how to use them.
To that end, I would advocate following these rules:
Project names should be identical to the root namespace of that project. I differ from this point myself where in some cases I name my projects "...Core", and I then remove "Core" from the namespace, but otherwise, leave the project name identical to the namespace
Use folders in the project to build namespace hierarchies
The name of a type should correspond 100% to the name of the file + whatever extension is right for your language. So "YourType" should be "YourType.cs", "YourType.vb" or "YourType.whatever" depending on language
That depends on who you ask.
I, personally, find it easier to read if they are all, always, broken out. However, the compiler doesn't care... so whatever you and your team agree is easier to understand.
In my opinion it's a good practice to avoid that. Some day a developer will be looking around for ClassBar in the project and won't be able to find it easily because it's nested in ClassFoo.cs
Tools like Resharper have a neat feature where you can just select a class, right click, place in new file to make this easier.
If you read any of the popular coding standards (Lance Hunt, iDesign, Framework Design Guidelines etc) most of them advocate 1 class per file.
Its annoying to scroll down and search for how many class each.cs file contains/hides.
Maintainability issue while using version control
Usability with our team.
Check here for more interesting discussion on same.
I think it was less about whether you can or whether you should. For things like this, I feel it's best to look to the convention in the rest of the codebase. Sometime conformity is better because it makes other developers jobs easier becaues everybody knows where things are.
If it's entirely new project and you are setting the standards here by yourself, do what makes sense to you. To me if the struct has no use outside the related class, I may put them in the same file. Otherwise, I seperate them out.
I know this is a subjective question, but I'm always curious about best-practices in coding style. ReSharper 4.5 is giving me a warning for the keyword "base" before base method calls in implementation classes, i.e.,
base.DoCommonBaseBehaviorThing();
While I appreciate the "less is better" mentality, I also have spent a lot of time debugging/maintaining highly-chained applications, and feel like it might help to know that a member call is to a base object just by looking at it. It's simple enough to change ReSharper's rules, of course, but what do y'all think? Should "base" be used when calling base members?
The only time you should use base.MethodCall(); is when you have an overridden method of the same name in the child class, but you actually want to call the method in the parent.
For all other cases, just use MethodCall();.
Keywords like this and base do not make the code more readable and should be avoided for all cases unless they are necessary--such as in the case I described above.
I am not really sure using this is a bad practice or not. base, however is not a matter of good or bad practice, but a matter of semantics. Whereas this is polymorphic, meaning that even if the method using it belongs to a base class, it will use the overriden method, base is not. base will always refer to the method defined at the base class of the method calling it, hence it is not polymorphic. This is a huge semantic difference. base should then be used accordingly. If you want that method, use base. If you want the call to remain polymorphic, don't use base.
Another important point to take into consideration is that while you haven't currently overridden that method that doesn't mean you won't ever in the future and by prefacing all of your calls with base. you won't get the new functionality without performing a find and replace for all your calls.
While prefacing calls with this. will not do anything other than decrease / increase readability (ignoring the situation where two variables in scope have the same name) the base. prefix will change the functionality of the code you write in many common scenarios. So I would never add base. unless it is needed.
I think generally you should use base only when overriding previous functionality.
Some languages (C# does not) also provide this functionality by calling the function by it's base class name explicitly like this: Foo.common() (called from somewhere in Bar, of course).
This would allow you to skip upwards in the chain, or pick from multiple implementations -- in the case of multiple-inheritance.
Regardless, I feel base should be used only when needed to explicitly call your parent's functionality because you are or have overridden that functionality in this class.
It's really a matter of personal preference. If you like seeing "base." at the beginning of your members, you can easily turn off the rule (Go to Options>Inspection Severity>Code Redundancies>Redundant 'base.' qualifier). Don't let non-behavioral static code analysis rules affect your preferred coding style.
EDIT
One thing to consider is that the static code analysis in FXCop and R# are there to provide rules for all possible needs. To actually adhere to all of the rules simultaneously is a little onerous. You should define your preferred coding style (if you're working in a team, do it collectively), and stick with it. Modify your rules to match your coding standards, not vice versa.
I'm having some problems to come up with a sane type naming scheme for our new line of applications. I want to follow the .NET Framework Developer's Guide - Design Guidelines for Developing Class Libraries, but I'm starting to wonder if that's such a good idea.
I'd like to use the Company.Product.Feature namespace scheme as a basis.
Problem 1: We have our own control and form base classes, and I want these to go into the Company.Product.Forms namespace. However, according to the guidelines, we shouldn't let our type names be Control or Form, even if they are in our own Company.Product.Forms namespace, since they will clash with system types.
Problem 2: We have some distinct feature areas in the application and I want these to go into their own Company.Product.Feature namespace. Lots of these features have similar design, with a controller and some views, so under each Company.Product.Feature namespace I'd like to have types named Controller, SomeView, AnotherView, etc. However, according to the guidelines, we shouldn't have the same type names in different namespaces.
The only solution I see to overcome these problems is to prefix the types with something that in some way makes the namespaces redundant. Or not?
Microsoft clearly favors some redundancy. A common example is:
System.Xml.XmlDocument
General class names, even bound within a proper named namespace can cause headaches for the many programmers who like to avoid fully qualifying their class instantiations. "Document" could be an Xml, Html or word document. This ambiguity will cause endless confusion if you happen to import more than one namespace with a "Document" class.
I'd prefer Company.Product.UI, for some reason. I would use that naming for the web, too.
Regarding problem 1, if these are base types, you might include Base in the class name.
Then, you typically have a set of domain specific controls, which won't clash with built-in types.
If you also keep wrappers for common UI controls(TextBox, DropDownList etc), then i would actually recommend use a prefix for them,
maybe this prefix is an abbreviated name of the product.
And then, if you do that, then you might want to be consistent, and do it for all types,
regardless of whether they are ambigious names or not.
I tell you from my own experience.
You'll end up constantly hovering over variables to see their full type names, etc, you will use aliasing etc..
The code will be harder to read.
Problem 2: While at GUI layer, i tend to break these rules, because you will want naming consistency(common verbs; Show,Edit,List). If the guideline tells you otherwise, i would believe it is because it is simply not specific enough.
First post here in StackOverFlow, on an old question. Please, be kind with me :)
General class names, even bound within a proper named namespace can cause headaches for the many programmers who like to avoid fully qualifying their class instantiations. "Document" could be an Xml, Html or word document. This ambiguity will cause endless confusion if you happen to import more than one namespace with a "Document" class.
Microsoft MIGHT sometimes favor some redundency but it's not always de case.
As for the Document vs XMLDocument problematic, when you know there might be more than one type of document, why not just include the qualifying part of the namespace in the declaration?
For example :
Xml.XmlDocument
vs
Html.HtmlDocument
Instead of importing the XML and HTML namespace, why not just include the containing namespace? It would become like this :
Xml.Document
vs
Html.Document
If it makes logical sense, then do it. They are just guidelines, not the LAW. (not that you cant break that too.)
Having classes in the with the same name in different namespaces is just is against the guidelines for a reason, it makes reading the code just a little bit harder because when you see "Controller" you have to mentally map it to "Feature1.Controller" or "Feature2.Controller".
I would prefer to use Company.Product.Features.Feature1.Feature1Conroller with the redundant information or maybe Company.Product.Features.Feature1Controller if it bothers you (and I personally don't like having too many namespaces).
But feel free to break the guidelines, rules are there to make you think before you break them :-)
The .NET coding standards PDF from SubMain that have started showing up in the "Sponsored By" area seems to indicate that properties are only appropriate for logical data members (see pages 34-35 of the document). Methods are deemed appropriate in the following cases:
The operation is a conversion, such as Object.ToString().
The operation is expensive enough that you want to communicate to the user that they should consider caching the result.
Obtaining a property value using the get accessor would have an observable side effect.
Calling the member twice in succession produces different results.
The order of execution is important.
The member is static but returns a value that can be changed.
The member returns an array.
Do most developers agree on the properties vs. methods argument above? If so, why? If not, why not?
They seem sound, and basically in line with MSDN member design guidelines:
http://msdn.microsoft.com/en-us/library/ms229059.aspx
One point that people sometimes seem to forget (*) is that callers should be able to set properties in any order. Particularly important for classes that support designers, as you can't be sure of the order generated code will set properties.
(*) I remember early versions of the Ajax Control Toolkit on Codeplex had numerous bugs due to developers forgetting this one.
As for "Calling the member twice in succession produces different results", every rule has an exception, as the property DateTime.Now illustrates.
Those are interesting guidelines, and I agree with them. It's interesting in that they are setting the rules based on "everything is a property except the following". That said, they are good guidelines for avoiding problems by defining something as a property that can cause issues later.
At the end of the day a property is just a structured method, so the rule of thumb I use is based on Object Orientation -- if the member represents data owned by the entity, it should be defined as a property; if it represents behavior of the entity it should be implemented as a method.
Fully agreed.
According to the coding guidelines properties are "nouns" and methods are "verbs". Keep in mind that a user may call the property very often while thinking it would be a "cheap" operation.
On the other side it's usually expected that a method may "take more time", so a user considers about caching method results.
What's so interesting about those guidelines is that they are clearly an argument for having extension properties as well as extension methods. Shame.
I never personally came to the conclusion or had the gut feeling that properties are fast, but the guidelines say they should be, so I just accept it.
I always struggle with what to name my slow "get" methods while avoiding FxCop warnings. GetPeopleList() sounds good to me, but then FxCop tells me it might be better as a property.
Are there specific cases when one should use custom attributes on class instead of properties?
I know that properties are preferrable because of their discoverability and performance, but attributes... When should I definitely use them?
UPDATE:
Here is a post by Eric Lippert about this decision.
Eric Lippert has a great blog post tackling exactly this decision.
His summary is:
In short: use attributes to describe your mechanisms, use properties to model the domain.
I'd also add to that the consideration that an attribute value is effectively static - in other words it's part of the description of the type rather than any instance of the type.
One tricky bit can come when every instance of some base type has to have a property (e.g. a description) but different concrete derived types want to specify descriptions on a per-type basis rather than per-instance. You often end up with virtual properties which always return constants - this isn't terribly satisfactory. I suspect Delphi's class references might help here... not sure.
EDIT: To give an example of a mechanism, if you decorate a type to say which table it's from in the database, that's describing the data transfer mechanism rather than saying anything about the model of data that's being transferred.
There are two use cases:
1) Using a custom attribute that someone else has defined, such as the System.LoaderOptimization attribute that may be used on the Main method. These kinds of attributes are used to direct platform code such as the CLR, WPF, WCF or the debugger to run the code in a certain way, and can be very useful at times. Reading books on various platform topic is a good way to learn when and how to use these attributes.
2) Creating your own custom attribute and using it to decorate a class (or method, property, etc). These have no effect unless you also have code that uses Reflection to notice those attribute usages and change the behavior in some way. This usages should be avoided whenever possible because of very poor performance, orders of magnitude larger than, say, accessing a static member of a class.