Related
We have a group of developers moving from C++ to C# and WinRT. We used D'Oxygen as part of our C++ developer builds, and I'd like to continue to have document generation as part of the developer build in C#/WinRT.
It's easy to turn on XML Doc generation, and I believe that will provide warnings for malformed tags, but without actual HTML output, I think our developers will be missing valuable feedback.
Looks like NDoc is now defunct, and I took a quick look at Sandcastle, but found it rather complex. Ideally, I'm looking for something that doesn't unduly burden developers, or require them to remember extra steps as they edit, build, test, and commit. In other words, the best solution would be something that "just happens", like a post-build step, and doesn't add significantly to each developer's build time.
If anyone has had some experience doing this in C#/WinRT, I'd sure like some advice.
Thanks in advance!
Get Sandcastle Help File Builder.
Create a help project for your library in the Visual Studio solution.
Remove Build check mark from Debug solution configuration to build the documentation project only in Release configurations, since Debug is most often used during development. For release build testing or performance testing you can either create another solution configuration or simply switch the option back and forth.
Build the documentation once
Include the documentation file in the solution so it shows up in the Pending Changes window when the file changes.
Kindly ask your developers to build with the release configuration that updates the documentation before check-in or use any other policy to require updating the documentation.
I don't think it makes sense to build the documentation all the time, but it helps to make it easy to do so that when you actually need an updated version - you can build it really quickly.
You can also make sure to use FXCop or StyleCop (forgot which) and configure it to treat missing XML documentation warnings as errors - at least in release builds. Doing it for debug configurations might slow down development and make changes difficult since developers often want to try things out before committing to a final implementation worth documenting.
EDIT*
Sandcastle provides various output formats as shown in the project properties:
I would like to mention ForgeDoc (of which I'm the developer), it could be what you are looking for. It is designed to be fast and simple, and it generates proper MSDN-like HTML output. It also has a command-line interface so you can just call it from a post-build event command in Visual Studio.
I think you should give it a try, as I would really like to hear about your thoughts.
Since MathWorks release a new version of MATLAB every six months, it's a bit of hassle having to set up the latest version each time. What I'd like is an automatic way of configuring MATLAB, to save wasting time on administrative hassle. The sorts of things I usually do when I get a new version are:
Add commonly used directories to the path.
Create some toolbar shortcuts.
Change some GUI preferences.
The first task is easy to accomplish programmatically with addpath and savepath. The next two are not so simple.
Details of shortcuts are stored in the file 'shortcuts.xml' in the folder given by prefdir. My best idea so far is to use one of the XML toolboxes in the MATLAB Central File Exchange to read in this file, add some shortcut details and write them back to file. This seems like quite a lot of effort, and that usually means I've missed an existing utility function. Is there an easier way of (programmatically) adding shortcuts?
Changing the GUI preferences seems even trickier. preferences just opens the GUI preference editor (equivalent to File -> Preferences); setpref doesn't seems to cover GUI options.
The GUI preferences are stored in matlab.prf (again in prefdir); this time in traditional name=value config style. I could try overwriting values in this directly, but it isn't always clear what each line does, or how much the names differ between releases, or how broken MATLAB will be if this file contains dodgy values. I realise that this is a long shot, but are the contents of matlab.prf documented anywhere? Or is there a better way of configuring the GUI?
For extra credit, how do you set up your copy of MATLAB? Are there any other tweaks I've missed, that it is possible to alter via a script?
shortcuts - read here and here
preferences - read http://undocumentedmatlab.com/blog/changing-system-preferences-programmatically/
At the moment, I'm not using scripts, though this sounds like a very interesting idea.
Unless there are new features that you also want to configure, you can simply copy-paste the old preferences into the new prefdir. I guess this should be doable programmatically, though you might have to select the old prefdir via uigetdir. So far, this has not created major problems for me. Note also that in case of a major change in the structure of preferences, any programmatic version would have to be rewritten as well.
I'm adding paths at each startup, so that I don't need to think of manually adding new directories every time I change something in my code base (and I don't want to have to update directory structures for each user). Thus, I also need to copy-paste startup.m for each installation.
If I had to do everything manually, I'd also want to change the autosave options to store the files in an autosave directory. If I recall correctly, Matlab reads the colors and fonts from previous installations, so I don't have to do that.
I have an subversion server running with Apache mod_dav_svn and it works nicely but the browsing ability via HTML is a bit spartan. Is there a way to customize it at all?
There's two things I'd like to do to make a huge difference:
separate the directories from the files so all the directories are at the top. Right now everything is in alphabetical order. (the picture above happens to have all the directories preceding files in alphabetical order, but trust me, that's not the normal case)
List the basic file statistics (file size, mod time, last updated version, etc)
Is it posssible to do either of these with mod_dav_svn?
In a vanilla Subversion install, the web interface is very spartan by design. (Remember the HTTP interface is designed for SVN clients, not human beings.)
You can customize the display somewhat via the SVNIndexXSLT directive. (Here is a good place to start).
If you want something richer (with logs and diff features), you will need to install a special front end. WebSVN and ViewVC are very popular. There is also Trac, but this is a higher-level tool.
A list of other repo browsing tools.
Just FYI, we use WebSVN for our repo instance. It took some effort to get it up and running, but once it is setup you can pretty much leave it alone.
WebSvn looks like it might help you. I tried trac and it is very slick but I found it to be complicated and seems overkill for what you're looking for, imo.
Not out of the box - that is, without modifying the source code. You might be interested in tools like ViewSVN or the more sophisticated trac or redmine.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
What tweaks / addins / themes do you have rigged up to make your IDE awesome? For example, in Visual Studio I color themes, CodeRush draws lines between braces, I always install and use the Consolas font and I have it setup to sync my settings across computers for when I change hotkeys and whatnot with the help of FolderShare.
Also, this isn't Visual Studio specific, please feel free to mention what you do with Emacs or Eclipse or whatnot as many of us use a few.
ReSharper 4.1 for Visual Studio 2008. It's a beautiful thing. It looks for all kinds of code errors, optimizations, etc. My code is cleaner thanks to this handy Visual Studio plugin.
Optimizing the IDE will be the first step. Resharper helps a lot but sometimes some simple macros are more than enough.
First things first. Change the font from the default crappy one. Then start fiddling with the 'Options' dialog box.
At the recommendation of a friend, I installed Visual Assist for Visual Studio 2008 -- it is awesome. I swear it can read my mind.
[Note: I have no affiliation with them -- just a very happy customer]
I've done a lot, but I really shouldn't have. So in the last few years, I've toned down the number of macros, custom key mappings, custom toolbars, etc. For the most part, I'm of the opinion that developers should get used to the default behavior and appearance of their IDE. Then when you need to work on your colleague's machine, you still know how to get around and manage to help them out. Not to mention that a whole slew of customizations will get broken or rearranged or otherwise reset when an update comes out.
That said, there are a few things that I still do every time I set up an IDE to work on... for example, setting the number of concurrent builds in Visual Studio to be 1, because that feature is so broken that nothing will compile correctly with any greater setting. Apart from that, being an ace with the default behavior will ultimately make you more efficient than spending hours tweaking the software to make it just a little more fluid.
I like CodeSmart VB6 and CodeSmart VS.NET from Axtools http://www.axtools.com/
for advanced syntax highlighting, drawing lines between parts of If..then..else..endif, Do While ... loop and all other constructs. It also has great code auditors and many add-in functions.
Vi plugin!!
I use Emacs. My .emacs file is only a few hundred lines long, but does customize settings based on my machine's hostname and operating system, so that I can use the same config file pretty much anywhere.
Colorization - Custom - White Text on GreyishBlack, Consolas Font
HotKeys - CTRL+SHIFT+ALT+Z (Attach to Process) probably some others too...
Addins - DPack, Coderush, GhostDoc.
Toolbars Off
All Windows set to collapsed
I am not doing presentations with this machine - If I was it would be barebones.
eclipse plugins make my ide exactly the way I want it of course.
eclipse plugin central
I kinda like the default setup of VS, I only make sure about Consolas as the editor font, and tabsize 2 (tabs to spaces), and change the color of numbers (red).
For Java development using Eclipse I have a few plugins that are indispensable. The MyEclipse Workbench adds a lot of functionality to most of the built-in modules. It makes it very easy to deploy an application to multiple application servers, and enhances a lot of the built-in editors. The PMD plugin is great for searching for potential code issues. As mentioned in a previous post today, the Ganymede plugin really helps to highlight log entries.
I dont care much for fancy visual addons, so I left my IDE (Visiual Studio) in the standard look (other than MS Reference Sans Serif font).
I usually change the color scheme to have a black background instead of white.
I use the Zenburn color scheme with Proggy Clean for a font. It's like a comfy chair for my eyes.
Nothing. I hate dealing with all the breakages that inevitably result from updates, etc. So, I adapt myself to my IDE instead.
I've using a combination of ViEmu and ReSharper with a dark theme.
Oh, and I also hide most of the toolbars and turn off the animations to try to speed things up.
Silver background, 8pt Consolas, disable all toolbars and set tab spacing to 3 spaces. :)
For Visual Studio
Most important - Resharper - I bought my own copy so I don't have to badger my employer about it.
Change the colourisation/font - choose whatever suits you
Optimisation (vote up Gulzar's post with the link in it)
Don't try and make the IDE do everything, just because you can. (Kind of ironic seeing I use emacs as well). I personally really dislike integrated source code management.
Change some defaut file associations so double clicking certain file types doesn't kick off Visual Studio
Aside from Resharper I've actually found most other beneficial thing is not customising the IDE, but customising yourself to learn the keyboard shortcuts. Start with the big gains like Ctrl -, Ctrl Shift -, Ctrl Shift V, Ctrl Alt L etc. etc. and then gradually learn the rest of the shortcuts in order of how often you'd use them
Rather than customizing the IDE, I customized my error messages. I have a macro that expands to a #pragma warning statement that generates a compile-time message in the same format as MSVC++. Visual Studio can parse the resulting warning, so a double-click on the message opens the offending file in the IDE and takes me right to the line in question.
I've used the macro:
To "bookmark" a section of code, so developers will be nagged to fix it each time they build.
Within #if blocks to test for various compile-time conditions.
In headers, to see who #includes them, and where.
From vim you can set the makeprg (make program) variable to a command that will build your project, and the errorformat variable to a scanf-style string that describes the format of the build errors. From there:
:make will build your project
:cl lists all of the errors that match errorformat
:cc takes to you the current error
:cn takes you to the next error
:cp takes you to the previous error.
Out of the box, vim sets makeprg and errorformat to work with make and gcc, and all of the commands are documented within vim's built-in help.
I do Java development in Eclipse. Here are some of the plug ins I find useful:
Mylyn - hides project elements not relevant to the current context.
eUML2 - UML editor.
FindBugs - Static analysis tool to find common bugs in Java.
Crap4J - Another static analysis tool.
EclEmma - Code coverage plug-in for unit tests.
Edit: I forgot one:
Disable the spellchecker. :)
In visual studio 2005 I do these:
Bind F11 to fullscreen mode
Enable a vertical line at 80 characters: HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0\Text Editor\Guides = "RGB(196,196,196) 80" (Guides won't be present in the registry.)
Add the "Start Debugging", "Break All" and "Stop Debugging" buttons after the "Help" menu.
I am using Vim Cscope plugin.
Cscope is like 'ctags' on steroids and makes traversing code much easier.
I usually use it along with tags to find where a function is declared and then go directly to whatever code is calling this function.
I also use Vim's Rgrep plugin (recursive search) to search for files in the code hierarchy.
Create some basic macro such as printing bug fix code comments:
Public Sub WriteBugFix()
Dim TS As TextSelection = DTE.ActiveDocument.Selection
TS.Text = "'Edited for Bug Fixed By JK - " & Date.Now.ToShortDateString
End Sub
(This answer assumes the workstation is a GNU/Linux computer.)
Emacs makes an excellent IDE specifically because it can be greatly customized.
You customize Emacs by editing the .emacs file in your home directory. My .emacs is a symbolic link:
$ ln -s /home/bzimmerly/bin/emacs/emacs24/wbz.emacs.el .emacs
Since Emacs offers a variety of specialized major modes for program development and debugging, you can easily "roll your own" IDE design that works best for you. For example, when I'm programming in C or assembler, I like to have the left side running GDB mode, with the right side displaying the source being traced.
A little bit of LISP skill goes a long way to turning Emacs into a very powerful IDE. It is well worth the investment of time to learn how to use this powerful tool!
Finally, tools like Youtube are valuable places for learning how to do this. Just entering "Emacs as an IDE" on the Youtube search form will show videos of how people have modified Emacs for just such a purpose. There are videos on editing Python code, Javascript, Java, C, etc.
What are your opinions on developing for the command line first, then adding a GUI on after the fact by simply calling the command line methods?
eg.
W:\ todo AddTask "meeting with John, re: login peer review" "John's office" "2008-08-22" "14:00"
loads todo.exe and calls a function called AddTask that does some validation and throws the meeting in a database.
Eventually you add in a screen for this:
============================================================
Event: [meeting with John, re: login peer review]
Location: [John's office]
Date: [Fri. Aug. 22, 2008]
Time: [ 2:00 PM]
[Clear] [Submit]
============================================================
When you click submit, it calls the same AddTask function.
Is this considered:
a good way to code
just for the newbies
horrendous!.
Addendum:
I'm noticing a trend here for "shared library called by both the GUI and CLI executables." Is there some compelling reason why they would have to be separated, other than maybe the size of the binaries themselves?
Why not just call the same executable in different ways:
"todo /G" when you want the full-on graphical interface
"todo /I" for an interactive prompt within todo.exe (scripting, etc)
plain old "todo <function>" when you just want to do one thing and be done with it.
Addendum 2:
It was mentioned that "the way [I've] described things, you [would] need to spawn an executable every time the GUI needs to do something."
Again, this wasn't my intent. When I mentioned that the example GUI called "the same AddTask function," I didn't mean the GUI called the command line program each time. I agree that would be totally nasty. I had intended (see first addendum) that this all be held in a single executable, since it was a tiny example, but I don't think my phrasing necessarily precluded a shared library.
Also, I'd like to thank all of you for your input. This is something that keeps popping back in my mind and I appreciate the wisdom of your experience.
I would go with building a library with a command line application that links to it. Afterwards, you can create a GUI that links to the same library. Calling a command line from a GUI spawns external processes for each command and is more disruptive to the OS.
Also, with a library you can easily do unit tests for the functionality.
But even as long as your functional code is separate from your command line interpreter, then you can just re-use the source for a GUI without having the two kinds at once to perform an operation.
Put the shared functionality in a library, then write a command-line and a GUI front-end for it. That way your layer transition isn't tied to the command-line.
(Also, this way adds another security concern: shouldn't the GUI first have to make sure it's the RIGHT todo.exe that is being called?)
Joel wrote an article contrasting this ("unix-style") development to the GUI first ("Windows-style") method a few years back. He called it Biculturalism.
I think on Windows it will become normal (if it hasn't already) to wrap your logic into .NET assemblies, which you can then access from both a GUI and a PowerShell provider. That way you get the best of both worlds.
My technique for programming backend functionality first without having the need for an explicit UI (especially when the UI isn't my job yet, e.g., I'm desigining a web application that is still in the design phase) is to write unit tests.
That way I don't even need to write a console application to mock the output of my backend code -- it's all in the tests, and unlike your console app I don't have to throw the code for the tests away because they still are useful later.
I think it depends on what type of application you are developing. Designing for the command line puts you on the fast track to what Alan Cooper refers to as "Implementation Model" in The Inmates are Running the Asylum. The result is a user interface that is unintuitive and difficult to use.
37signals also advocates designing your user interface first in Getting Real. Remember, for all intents and purposes, in the majority of applications, the user interface is the program. The back end code is just there to support it.
It's probably better to start with a command line first to make sure you have the functionality correct. If your main users can't (or won't) use the command line then you can add a GUI on top of your work.
This will make your app better suited for scripting as well as limiting the amount of upfront Bikeshedding so you can get to the actual solution faster.
If you plan to keep your command-line version of your app then I don't see a problem with doing it this way - it's not time wasted. You'll still end up coding the main functionality of your app for the command-line and so you'll have a large chunk of the work done.
I don't see working this way as being a barrier to a nice UI - you've still got the time to add one and make is usable etc.
I guess this way of working would only really work if you intend for your finished app to have both command-line and GUI variants. It's easy enough to mock a UI and build your functionality into that and then beautify the UI later.
Agree with Stu: your base functionality should be in a library that is called from the command-line and GUI code. Calling the executable from the UI is unnecessary overhead at runtime.
#jcarrascal
I don't see why this has to make the GUI "bad?"
My thought would be that it would force you to think about what the "business" logic actually needs to accomplish, without worrying too much about things being pretty. Once you know what it should/can do, you can build your interface around that in whatever way makes the most sense.
Side note: Not to start a separate topic, but what is the preferred way to address answers to/comments on your questions? I considered both this, and editing the question itself.
I did exactly this on one tool I wrote, and it worked great. The end result is a scriptable tool that can also be used via a GUI.
I do agree with the sentiment that you should ensure the GUI is easy and intuitive to use, so it might be wise to even develop both at the same time... a little command line feature followed by a GUI wrapper to ensure you are doing things intuitively.
If you are true to implementing both equally, the result is an app that can be used in an automated manner, which I think is very powerful for power users.
I usually start with a class library and a separate, really crappy and basic GUI. As the Command Line involves parsing the Command Line, I feel like i'm adding a lot of unneccessary overhead.
As a Bonus, this gives an MVC-like approach, as all the "real" code is in a Class Library. Of course, at a later stage, Refactoring the library together with a real GUI into one EXE is also an option.
If you do your development right, then it should be relatively easy to switch to a GUI later on in the project. The problem is that it's kinda difficult to get it right.
Kinda depends on your goal for the program, but yeah i do this from time to time - it's quicker to code, easier to debug, and easier to write quick and dirty test cases for. And so long as i structure my code properly, i can go back and tack on a GUI later without too much work.
To those suggesting that this technique will result in horrible, unusable UIs: You're right. Writing a command-line utility is a terrible way to design a GUI. Take note, everyone out there thinking of writing a UI that isn't a CLUI - don't prototype it as a CLUI.
But, if you're writing new code that does not itself depend on a UI, then go for it.
A better approach might be to develop the logic as a lib with a well defined API and, at the dev stage, no interface (or a hard coded interface) then you can wright the CLI or GUI later
I would not do this for a couple of reasons.
Design:
A GUI and a CLI are two different interfaces used to access an underlying implementation. They are generally used for different purposes (GUI is for a live user, CLI is usually accessed by scripting) and can often have different requirements. Coupling the two together is not a wise choice and is bound to cause you trouble down the road.
Performance:
The way you've described things, you need to spawn an executable every time the GUI needs to d o something. This is just plain ugly.
The right way to do this is to put the implementation in a library that's called by both the CLI and the GUI.
John Gruber had a good post about the concept of adding a GUI to a program not designed for one: Ronco Spray-On Usability
Summary: It doesn't work. If usability isn't designed into an application from the beginning, adding it later is more work than anyone is willing to do.
#Maudite
The command-line app will check params up front and the GUI won't - but they'll still be checking the same params and inputting them into some generic worker functions.
Still the same goal. I don't see the command-line version affecting the quality of the GUI one.
Do a program that you expose as a web-service. then do the gui and command line to call the same web service. This approach also allows you to make a web-gui, and also to provide the functionality as SaaS to extranet partners, and/or to better secure the business logic.
This also allows your program to more easily participate in a SOA environement.
For the web-service, don't go overboard. do yaml or xml-rpc. Keep it simple.
In addition to what Stu said, having a shared library will allow you to use it from web applications as well. Or even from an IDE plugin.
There are several reasons why doing it this way is not a good idea. A lot of them have been mentioned, so I'll just stick with one specific point.
Command-line tools are usually not interactive at all, while GUI's are. This is a fundamental difference. This is for example painful for long-running tasks.
Your command-line tool will at best print out some kind of progress information - newlines, a textual progress bar, a bunch of output, ... Any kind of error it can only output to the console.
Now you want to slap a GUI on top of that, what do you do ? Parse the output of your long-running command line tool ? Scan for WARNING and ERROR in that output to throw up a dialog box ?
At best, most UI's built this way throw up a pulsating busy bar for as long as the command runs, then show you a success or failure dialog when the command exits. Sadly, this is how a lot of UNIX GUI programs are thrown together, making it a terrible user experience.
Most repliers here are correct in saying that you should probably abstract the actual functionality of your program into a library, then write a command-line interface and the GUI at the same time for it. All your business logic should be in your library, and either UI (yes, a command line is a UI) should only do whatever is necessary to interface between your business logic and your UI.
A command line is too poor a UI to make sure you develop your library good enough for GUI use later. You should start with both from the get-go, or start with the GUI programming. It's easy to add a command line interface to a library developed for a GUI, but it's a lot harder the other way around, precisely because of all the interactive features the GUI will need (reporting, progress, error dialogs, i18n, ...)
Command line tools generate less events then GUI apps and usually check all the params before starting. This will limit your gui because for a gui, it could make more sense to ask for the params as your program works or afterwards.
If you don't care about the GUI then don't worry about it. If the end result will be a gui, make the gui first, then do the command line version. Or you could work on both at the same time.
--Massive edit--
After spending some time on my current project, I feel as though I have come full circle from my previous answer. I think it is better to do the command line first and then wrap a gui on it. If you need to, I think you can make a great gui afterwards. By doing the command line first, you get all of the arguments down first so there is no surprises (until the requirements change) when you are doing the UI/UX.
That is exactly one of my most important realizations about coding and I wish more people would take such approach.
Just one minor clarification: The GUI should not be a wrapper around the command line. Instead one should be able to drive the core of the program from either a GUI or a command line. At least at the beginning and just basic operations.
When is this a great idea?
When you want to make sure that your domain implementation is independent of the GUI framework. You want to code around the framework not into the framework
When is this a bad idea?
When you are sure your framework will never die