I like intellisense and I think everyone should always add structured comments on classes and methods, I say so because the concept of being "self commenting code" is per se a wrong practice.
How do you draw the line between something that for the creator is obvious but this isn't true for any other developer?
In my company we have a wide range of very useful shared NuGet packages, but most of them have no comments, or at least in the interfaces. This cause the consumer class, using IoC, to blindly use the interfaces loosing completely the comments and therefore the intellisense.
Maybe I don't create the NuGet packages in the right way, but so far the best practice I found, is to add comments in the interfaces and add in the implementing class, the comment: /// <inerithdoc cref=""/>.
This helps me share the documentation, parameters and return type descriptions and so on.
Now the inherithdoc, is mostly used for the XML documentation generation, but not really helpful when it comes to access the description from the implementation class.
An example, I have IMyClass with all the nice comments, if I open MyClass which implements IMyClass, I can read through the code but I don't have straight access to the comments and it is very annoying to be forced to jump back and forth to the Interface in order to read them.
So a possible solution would be to copy the comments across Interfaces and implementing Classes, but I hate duplication, and you can easily end up updating the descriptions here but not there.
So my question for the community is, how do you handle this? Is there Any extension that shows me the description maybe as part of the codelens?
Hovering the mouse on the cref attribute, allow me to get the description of the class/interface and methods, but not parameters.
Related
I'm looking to share an EF Context between "data manager" objects to ensure change tracking occurs under one context as opposed to handling multiple contexts...so I'm looking into named context... but in review of this documentation, I felt it wasn't clear, and I want to ensure my assumption is correct, and if so, update the documentation: here PRISM documents the resolution of named instances via a constructor:
My assumption is that the named typed "carservice" is matched to the named parameter in the constructor to select which concrete class should be reference to that parameter based on the IVehicleService.
Is my assumption correct - either way I'll create a pull request to clarify the documentation..Either way, answering the question here will add reference to clarification/handling of named instances in PRISM.
It seems this is NOT correct assumption, and it's not possible in Unity - I refactored to avoid.
One solution that I didn't try was to simply another interface (came to mind much later), was inheriting from an existing interface, and registers the "new" interface to use a specific constructor. As I'm new to Unity, I thought I would mention. I'm answering my own question, as I can't don't think I can give credit to a comment, and I HATE leaving questions unanswered on this site!
I've been learning Go for a class course and I am very excited with the language, it really is very useful for web services.
So, I've been writing this CRUD restful API for a final project and I keep running in the damn circular dependency problem. I've already researched and read on the ways of solving it and will post here just for the sake of it, but first the problem I am having:
routes need to know about the handler functions in the handlers package, which in turn need to know about the user structure inside the model package, which in order to send a registration e-mail with a link need to know about the routes path
Classical A -> B -> C -> A
Now, I am trying to write this API using MVC and three layer architecture, this I would love for my routes to be in a controller package, my handlers to be on a business logic package and my user on a model package. This is also needed because I have over 43 model classes, I need them tidy up and tucked away on their package.
Ok, the solutions I found out
1 - Throw everybody on the same package : That's what I've been doing so far but is a very horrible solution for obvious reasons.
2- Pass whatever user needs as argument when it's functions are called: That would be a good solution, but won't work because the function that is being called from user is from an interface implementation because it has to be a generic call and before anyone goes around saying that my problem is because I am forcing generics in go, well too bad, I need that generic, I will not write over 160 crud functions. The whole point of functions is to avoid code repetition.
3- Create another package, with another interface, and have it having a instance of handlers and user and have it pass arguments from one to the other: Despite the reason mentioned above, the need of generic, this sounds like an unnecessarily complicated solution, I refuse to believe that this is better design than circular dependencies.
Bottom line question: How to solve this dependency when C needs to know information from A and generics must be respected
I can post some code here if you need to but I don't see the relevance of specific code when this is more of a high level question.
EDIT: Solved my dependency problem. Thank you all for the comments and answer as it led me to the answer. I don't think I've implemented any of the solutions suggested but it did taught me a lot about how to solve the problem, and they would all be very acceptable and doable solution if it wasn't for my own constrains where I don't want to pass anything to User.
To anyone trying to solve their own dependency problem, what I was able to gather is, instead of making in my case, C ask something from A, give to C whatever it needs, before it has to ask, meaning pass the information to him.
Alas, that was not my solution, what I did was remove the information from A and give the information to Z, now both A and C are asking the path information to Z, which is just a Map, sitting there being all map like and holding information.
Thank you all
You've got some options, and you've found some of them. The main ways of handling this are:
Refactor your design to turn the cycle into a tree. This doesn't really apply to your situation due to your requirements.
Refactor your design to use some kind of dependency injection (this is your 2nd option in your question). This is perfectly viable, and probably the cleanest and easiest.
Refactor your design to take a locally declared interface. This is a more Go-idiomatic version of your option 3. Because interfaces in Go are duck-typed, you get to define it where it's consumed, rather than where it's implemented. So your user package can define a one-method interface for "a thing that gives me a URL I need" and it never needs to reference the package that implements the interface.
If we omit visibility modifiers(let's say all methods are public), is there any common convension to put new methods in class? I mean if I put them on bottom it's logically correct, because methods are sorted by date. If I put them on top, it's easy to see and compare what methods are added if the class is very long.
Just depends on what you and your team are comfortable with. I usually have method at the top of my class followed by fields. If there are many method that do different thing you are better off organizing them in a new class. Now without seeing any code I'm simply guessing.
No, I don't think there is.
As Kalagen said it's up to you and your team to decide it.
I would keep any methods that share similar functionality together and keep the class definition short.
The short answer in my opinion is no. Coding style might vary depending on the language you are using and the team you are working with. In addition you might have your own preference as well. I tend to add new methods close to methods that are related to it (e.g. if method1 calls method2 then method1 is above method2). Then it is relatively easy to find the method that's being called. On the other hand, most IDEs can find the method with a mouse click.
If you're using version control, you can easily see what methods were added and in which order, so sorting by date is not needed.
And as others have mentioned, keep the class small. Take a look at the Single responsibility principle. If the methods you are adding are not related to the responsibility of the class, extract them and create a new class.
D2D1 is the namespace for Direct2D technology in Win32. However I don't understand the etymology of this name. The D2D part most likely refers to Direct2D, however the last 1 puzzles me...
There are also a lot of classes with "1" as a suffix: IDWriteFactory1, IDWriteFont1, IDWriteTextLayout1, etc. — what is their purpose, and difference from the similar objects without the suffix?
COM interfaces are usually named with increasing numbers to allow for versioning. Once a COM interface has been published publically, COM rules dictate that the interface is not allowed to be changed anymore, or else compatibility with existing code breaks. If new functionality needs to be added, a new interface has to be exposed. Let's take IDWriteFactory1 for example. Today, that is a first release interface. In the future, maybe IDWriteFactory2 will be added that extends IDWriteFactory1 with new methods. Existing code is preserved, since they don't know anything about IDWriteFactory2, but new code could create an IDWriteFactory1 object and query it to see if it supports IDWriteFactory2 and if so then use the newer methods as needed.
The naming of the D2D1 namespace is likely similar. It is probably being used for versioning purposes (Direct2D v1 ?). Maybe there will be a D2D2 (Direct2D v2) namespace added in the future for things that don't fit in the existing Direct2D architecture. Who knows for sure.
So thanks to the Visualization and Modeling Feature Pack , I can build a uml model diagram and generate a bunch of classes.
But what now? Presumably, my developers will add code to those classes. Useful code, valuable code, and as the templates themselves indicate:
// Changes to this file will be lost if the code is regenerated.
So what is the best solution here? Can I make the modeling project reflect changes to the actual classes? Should I generate partial classes? Modify the default templates to read class files and not auto-generate anything that has been modified? Should I tell developers not to edit model files under pain of....well, pain?
Thanks for the tips.
As far as I know, this is really the key reason for partial classes in the first place. The custom code goes in one file, the auto-generated in another.
You could also create classes derived from the generated ones, and put any changes in there. I also agree with above poster that partial classes could be the way to go.
Although the tools generate basic skeleton classes out of the box, that's really just a starting point. You can easily adapt the generator templates to create your own stuff. Different people want to generate different code from the classes - some even generate XML or SQL. And yep, in C#, partial classes are good to generate, so's to keep the hand-written code separate from the generated bits.
It's good to put lots of extension points in the generated code, where you fill in the details by hand code.
Another neat idea is "double derived": from each UML class, generate a base class and a derived class. The derived one has only constructors. The base class has any methods you generate. So your hand code can easily override generated methods where you need that.
There are several options in the tool and recommending what is best is hard without knowing your scenario. Partial classes are great for some, but not all applications. If you want your UML class to generate a partial class, you can set it's C# stereotype's property to "Partial" and it will do so, and custom code can then be added in a partial class that won't be overwritten. If you want to prevent code from being overwritten, you can do this by setting the overwrite property to False on the template binding that corresponds to the package you are working on. This lets you set your extension code to be in a package that is not overwritten, while your model mastered code is overwritten with the latest model changes. Finally, if you want your code to be the master for your model so it always reflects the latest code, then you can reverse engineer your code by using the architecture explorer to select your classes and then dragging them in to a UML diagram. So for a given gesture, either the model is the master or the code is the master. In this version, we did not implement automated merge capabilities between the two.