Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Basically, the question is: Where (and in which format) should I store textual developer documentation associated with my Visual Studio projects?
To elaborate: XML comments are great, but they don't cover all use cases. Sometimes, you'd like to describe the class architecture of the project at a high level, add usage notes to your library or just leave any other kind of message to future generations of developers working on this project.
I'd like to add these documents directly as files into the Visual Studio project, to ensure (a) that they are available to the developer without further searching and (b) they are version controlled (using the same svn/git/whatever repository as the source code).
Currently, I add a folder _Documentation to the project and use text files, but I'm not sure if this is the best solution. Visual Studio does not have an option for automatically word-wrapping text1, and manually fixing line breaks after each change is annoying. On the other hand, Word documents don't work well with version control, and TeX is too much of a hassle to set up and teach on each developer PC.
Is there a well-established best practice for this?
1 I know that there's Edit/Advanced/Word-Wrap, but this only affects the display, not the file itself.
I just had the same issue - only I noticed that I was able to add a HTML-file. Once opened, simply switch to "Design" at the bottom of the screen.
You may want to change Build Action from 'Content' to 'None'
As it is a hard-coded HTML document, it is also possible to use inline pictures (e.g. a diagram)
Also for my purpose (programming guide, architecture description. database use examples) I opted to create a separate project (_Documentation) as a Windows Forms, as this will allow me (or a new programmer) to have a running example.
I use GhostDoc (visual studio add-on) for documentation of my project as I add classes, methods, properties etc: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748
You have the option, in XML comments, to include a lot of data that you can then pick up with a tool like Sandcastle (site) and turn into an actual MSDN-style reference site.
I tend to use this method and just write long XML comments (MSDN comment tags) (where appropriate) using the <para></para> to generate paragraphs and explain any patterns, business reasons or architectural information necessary to future modifiers/developers. I also use it to give usage examples.
A good batch of tests (well written and named) can also really illuminate the purpose of code, acting as a spec.
I hope that might be a little informative in your research :)
XML Comments is best for documenting the particular method and not ideal for writing long conceptual content. Long XML comments could adversely affect code readability.
I liked Conceptual topic documentation feature of Sandcastle, we can create and store Conceptual documentation whether functional or architecture related and merge it with Code documentation (XML Comments). Markups which you can use in writing the conceptual topics are extendable which means we can even adhere to Enterprise templates.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I am writing a software suite which is essentially composed of two separate applications in C# .Net using WPF. Although they may look a little bit different they essentially work like a lite version and a full version of the same software package. The full version contains all of the functionality of the lite version.
I had previously done this by creating two separate applications which share a class library where all the common user controls go. But i am now wondering if there is any better design for this kind of architecture.
I was even thinking of creating one application and at runtime let it decide which version it was going to work as.
Could anyone with any experience with this type of problem please point me in the right direction.
Keep it Simple
My rule of thumb is whenever possible keep solution as simple as possible. That being said I would use the same composition you are using.
Usually break up projects like this:
Application Logic: CompanyPrefix.ProjectPrefix.Core, CompanyPrefix.ProjectPrefix.Data...etc.
Applications : CompanyPrefix.ProjectPrefix.ApplicationType.App, so some examples :
CompanyPrefix.ProjectPrefix.Web.App
CompanyPrefix.ProjectPrefix.Console.App
CompanyPrefix.ProjectPrefix.Wcf.App
Since you have two Wcf Apps might want to do something like
CompanyPrefix.ProjectPrefix.Wcf.Lite.App
CompanyPrefix.ProjectPrefix.Wcf.App
So in this example both CompanyPrefix.ProjectPrefix.Wcf.App and CompanyPrefix.ProjectPrefix.Wcf.Lite.App point back to CompanyPrefix.ProjectPrefix.Core or wherever your business logic is.
About Dynamically Loading Assemblies
There is a way to dynamically load your libraries at runtime, but unless you're dealing with a modularized system of independent components would recommend against it.
If your heart is set on it there are a lot of resources on MSDN, would probably start here. Article about loading assembly into current application domain.
Come Up with a Checklist
One thing I find helpful is to come up with a checklist to help me make decisions in case I ever get stuck. Usually ends up being something like:
Does this have business value?
Does this make debugging harder?
What are the Pros and Cons of doing it a new way versus the way I have done this in the past?
This isn't my exhaustive list but explains the point. This can really help too when you have a group of people that are largely sticking with choices for personal reasons that don't have any grounding, as well as a tool to use when you get stuck to make a decision and go with it
Dealing with Application Logic Changing (Write Clean Code)
Coming up with an over-complicated "never need to recompile entire application again" is a mistake I have made in the past. You're still going to need to deploy and compile something.
Most important thing about dealing with changes in application is to
Have Code on Source Control (most important)
Write Clean Code
Write Tests
Write Documentation ( I know no one likes to do this )
Write some more Tests
What will consume most of your time when dealing with application changes is debugging so focus on reducing the amount of time you spend debugging not a amount of time you spend compiling and deploying
For Deployment setup Continuous Integration
If you have the ability to setting up CI would eliminate 99% of the hassle of changing the application. You lose a day or two setting things up for the first time, but it is well worth it.
Check out TeamCity and Travis CI
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
What tools/plugins do you use for checking in/out code?
how to communicate changes made to the code, how to make request for new functionality?
How has your team solved this?
See this previously asked question:
Multiple Programmers in Software Development. How do we work on the same code and ensure it is always updated?
There are a lot of good answers to this question, and they apply to small and large teams.
For source control, we use Svn with the Tortoise SVN client. We've used other source control systems in the past, and have found this one to be the best for our needs.
I would recommend you use SVN for source code management, if you are using visual studio you can get numerous plugins for IDE integration.
http://subversion.tigris.org/
http://www.visualsvn.com/ = SVN Server & VS Integration
Try to set up Continuous Integration for this you can use Cruise Control .Net or Hudson. Cruise control can be set up to do a build on each check in and the history is shown on a web page.
http://confluence.public.thoughtworks.org/display/CCNET/Welcome+to+CruiseControl.NET
http://hudson-ci.org/
For requesting new functionality you could use a ticketsing system, wiki or Google Wave any one of these should enable you to keep track of requirements.
Hope this helps.
You can pretty much use any tools for small development teams you wish. There are lots of options.
Personally, my team uses SVN for code, and Trac for tracking - mostly because it's very cost effective for a small team. However, there's nothing C#/.NET specific about that setup.
If your team has MSDN subscriptions, you might want to consider Team Foundation Server. It has many features for integration with Visual Studio that are (arguably) superior to some of the alternatives.
You should use one of the many available source control repositories. Trust me, you won't know what you did without it :)
There are plugins for Visual Studio for working on a team, but personally I've never used them.
I've done team projects with both Subversion and Mercurial... just make sure to check in the solution and project files, and all related code.
Everyone will also need to be running the same version of Visual Studio.
For requesting new functionality, you might want to consider an external solution like Trac or Bitbucket or some other free system that includes issue tracking.
Well, how small? I work on a team of 5, and we communicate well with IM, or just dropping by and talking. That being said, the team is pretty responsible, so you can trust everyone to carry their weight. I would suggest you use subversion for source control if your company doesn't have anything.
We're a team of 3 C# developers.
For version control, we use AnkhSVN, an open source SVN client that integrates with Visual Studio.
For project management, issue tracking and feature requests, we use Redmine.
What tools/plugins do you use for checking in/out code?
Mercurial -- once you've used a DVCS, it's hard to imagine going back. Everybody uses their own favorite editor; usually, that's Emacs, which comes with support for many VCSs, including Mercurial.
how to communicate changes made to the code, how to make request for new functionality?
Changes are tracked in version control. You can look at the changesets as you pull them, or browse the web interface. Or just ask people at lunch what you're working on -- no developer is an island. New functionality is tracked, along with bugs, in the bug tracker.
How has your team solved this?
We're a small team using C#, but nothing here is specific to C# or small teams. I've used very similar systems with other size teams, and other languages/platforms.
We have a team of three and currently use Source Gear Vault for source control and Fogbugz for bug/feature tracking. Source Gear integrates into Visual Studio nicely and works over http which makes it easy to access from anywhere. Check ins and outs can be done directly in Visual Studio or a standalone client.
Source Gear also integrates with Fogbugz.
Used to use Visual Source safe and would never go back...
I work on a small team of 1-5, depending on the project.
What tools/plugins do you use for checking in/out code?
We use Git with Github for new projects, and TFS for some legacy work.
I see a lot of people recommending a certain provider without telling you why. I have used TFS, SourceGear, SVN (a little), and Git. I prefer Git because it stays out of my way. Git is command-line based. My typical source control workflow is a handful of simple commands, but learning those commands took a few tries.
how to communicate changes made to the code, how to make request for new functionality?
We use Pivotal Tracker for story writing and organizing priority.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Does anyone know of a good and simple open source code snippet repository? Ive seen many that are free services, but I want to host it myself. A few google searches just find the free services.
I use Wordpress with WP-Syntax plug-in for that. Selfhosted, easy, and all done by couple clicks :)
Can you clarify what you mean? Do you want one for your own personal use (what is wrong with the built in snippet management in visual studio? Are you looking for examples of design patterns? In that case maybe check java2s or the portland pattern repository. For snippets such as looping constructs, try catches, etc i love Coderush templates.
That being said, my personal opinion is that snippets are as evil as copy-paste. What you probably want is to refactor so that there is no duplicate code. And if you need to share code between projects - some sort of core library might be the way to go.
Edit: In the comments below you specify that you want snippets available via web. I don't have anything to recommend thats exactly like that but you should look into storing your snippets in visual studio and syncing them using LiveMesh. I know of several people that do something similar and they like it.
OOoooor...what's wrong with just a wordpress blog? You can set it to private access only. You get tagging, searching, syntax highlighting (via the google syntax highlight plugin) and a nearly 0 fuss setup.
http://code.google.com or sourceforge not good enough? Also, there is GitHub if you preffer git to svn.
Granted, it's not for short snippets, mainly, but you could easely use it for that.
Edit
Reading again your question and your comments, what you really want is an existing, open source, system to hold short pieces of text made in c#?
I'd guess you'd have to do that yourself, I know of no project to do just that :S
I'm also trying to understand what you mean.
As the top commenter said, there's visual studio. Or there's Github but that's for more of version control and can have some annoying sides when trying to organise things.
There's also Snippet Repo which you can post snippets, favourite other people's stuff. I guess it's like a social code repository.
I'd still suggest using existing sites. I often use Google Codesearch when I'm looking for existing examples of how to use a function or boilerplate code (just watch licenses of the code you are borrowing from...)
But it sounds like you're looking to host a pastebin.
pastebin.com has source code available.
Other variations are available, and wikipedia has a good comparison of pastebin software.
git + gitosis + gitweb
I have a repository specifically for small one-off scripts I'm unlikely to change or expand. Doing something similar for a personal library doesn't seem unreasonable. You want to manage source code; that's what source control is for.
Krugle has an excellent base and allows for quick searching and filtering.
Active State has a some good snippets with excellent reasoning and documentation.
Take a look into OpenGrok in conjunction with a SVN setup.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
My boss thinks the VS 2008 IDE Window Manager(autohiding, docking of Solution Explorer, Properties, etc) is the best thing since sliced bread. I can't find a control that resembles that functionality in the Toolbox. Is there a control like that available that you know of? Or should I go ahead and implement it myself? Btw, we're using VS 2008 Express.
You don't have to create something that looks like the VS window manager - you can use the actual VS one with the Visual Studio Shell.
I believe it's aimed at creating developer tools, but I see no reason why it would have to be used that way. It's a bit like the Eclipse RCP, as I understand it.
I implemented in a real project the DockPanel Suit by Weifen Luo that worked very well and it is in production right now on a quite complex application (it is an application for the financial market that had very strict UI requirements in terms of performance and stability). It is really a very good implementation.
I even had to do some custom modifications and found the code to be very understandable and well written.
I'm sure there are several comparable comercial implementations from companies like Infragistics and similar, but if you are short on cash or just don't care for commercial support services for your components you can give it a try:
http://sourceforge.net/projects/dockpanelsuite
I just hope you're not developing a standard line of business app for non-technical users.
I was involved in a line of business app. that tried using the Magic library (from memory) and implemented property windows etc, so it looked "just like Visual Studio".
Then we released a prototype to the end users and they hated it. These were non-technical finance and accounts type people, some even power users. The major complaints were "windows don't stay in the same place", "too easy to accidently drag windows", "too fiddly" "my window keeps disappearing" etc etc.
Just because your boss thinks the Visual Studio IDE is great doesn't mean a thing if your target user group don't.
Don't forget that Visual Studio was designed/built by developers for developers. If your users aren't going to be overly technical it might be very wise to do some prototyping with them first.
There is a very good opensource project just for this. Look on SourceForge for DockingSuite Dock Panel Suite.
You should check out SandDock. The older versions were freely licenced (dunno if they are still available) and the newer versions are relatively cheap, especially considering the amount of time/money/sanity they would save you.
I would strongly recommend against trying to roll your own VM component. There is just too much work involved, and it wouldn't be worth it, if it wasn't your primary product.
Magic Libary
Dock Panel Suite
Dock Container
I personally think Magic Library is the best. Can't remember if it's OSS though.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 8 years ago.
Improve this question
Background: In my job, we use SVN, C# and VisualStudio. Part of my task regularly involves global renames. Often I end up with a broken build after renaming something and then merging in changes.
The question: is there a solution out there that can look at my changes, notice the global rename and then apply that to the edit that others have made while merging them in?
Another way to get much the same effect would be some sort of refactor log and then apply that to the incoming edits.
The tool need not be perfect, even if it just noted any references in their edits that referred to something that I have edited would be valuable.
Edit I'm aware of VS's refactor tools. What I'm looking for is something that will allow me to, after I have refactored my working copy, apply the same refactorings to other peoples edits that I now need to merge in.
The ideal solution would be to make sure there are no outstanding edits when I do the refactoring, but that would prevent anyone else from getting anything done for the next week or more. (Because they would have to sync every half hour or so for the next week)
There is a commercial tool for exactly that use case called Semantic Merge. They provide a 15-day free trial, open source projects may use it for free (contact the support).
The company behind semantic merge also has a git client with integrated Sematic Merge which is currently beta (here, have some short intro videos).
Keep renaming seperate from other refactorings. They can generally be automated and therefore making the changes is easy. You can even distribute scripts to allow other engineers with merge hell to perform the transformations on there files.
There is no easy way to automate refactorings, so keep it simple. A rename should only take minutes and you should be able to check out and commit with minimal testing.
Assuming at least VS 2005 and the global rename is a variable/property/function, there is a Refactor - Rename right-click menu option you could use. By design it propagates the name change in your entire solution.
Wouldn't it be possible to reduce the time needed for you to commit your changes? One or more week seems quite long between commits...
I understood your problem. Unfortunately, I think there isn't a SVN script smart enough to do this job while syncing.
Maybe your team working more appropriately with SVN could make this situation be unpainful. When you do an svn:update in your working copy and realize merging operations, it is a good practice to rebuild the updated solution before do commit the changes.
Having a svn script with the ability to doing it automagically when merging would be great, indeed.