I wrote an app in which there is a ton of comments.
This may be a bit unusual, but I would like to know if there is a way in Visual Studio to elegantly arrange the comments in a dedicated file. Or, is there a way to write text somewhere in a text file?
It is true that using comments is great, but my code is still congested.
Currently I plan to use a new class for comments, which will only contain comments with details on the parts of the code that are concerned.
If you have a better idea, thank you very much for sharing it.
I can't stress enough how much of a bad idea this is.
Code comments are best:
Being near the code they concern
Short and simple
Used sparingly - code often changes, comments can very quickly fall out of sync with this, and then before you know it the comments are doing more harm than good.
If there really is some functional explanation you're trying to get across, e.g. why something is needed and how it works, rather than how to use it, I'd recommend writing a document to explain this.
There are all sorts of ways to do this:
Word documents on a shared system (e.g. a network drive / sharepoint)
A wiki system online / internally (e.g. Atlassian Confluence, or GitHub wiki)
(to name a couple)
As per other user's suggestions though, you should ensure that there aren't a lot of comments as they just add noise (something you're clearly discovering).
Sidenote: I once worked for a company that insisted on using comments everywhere, every function had to have a banner comment with its name, signature, who wrote it and an edit history (even though we used source control), and nearly every line of code had to be commented to state what it was (supposedly) doing. If you're in a similar position, perhaps try to explain the problems this causes?
Related
There was a similar-ish question here on SO https://stackoverflow.com/questions/9475795/how-do-you-share-code-across-teams-working-on-very-different-projects but mine is about writing documentation.
Scenario:
Let's say my team is working on a software project, a Fany-WordPad like application which has a feature called Fancy-Word-Art ( just like MS Office's word Art). Now I wrote the code for the main window( using WPF in .Net, or using Window Builder in Java, doesn't matter which tool/language).
Now if my colleague Mr Spongebob is writing the Word-Art part, how would I tell him what functions to call / Api to use to draw on my window? i.e. How do I let Mr SpongeBob know that he needs to call GetWindow() method to get a reference to the drawing surface, the parameters he needs to pass along , and so on?
I hope I am being clear here. Is this the procedure?
Step 1 : Use your company wiki site to understand your colleague's written code
Step 2 : Write the GetWindow() method so that it works well with the rest of the project
Step 2 : Now put a wiki on your intranet with the method parameters/ data type requirement for your GetWindow() method or use Doxygen/ Confluence as suggested below
Step 3 : Now its your colleague Mr Spongebob's headache how to find how to draw his word-art on my window.
This just doesnt sound right .. With tons of functions, Spongebob's life will be hard, just as mine. Both of us rummaging through documentation to find the right functions to do our job. What if then I change GetWindow() to GetWindow(string title).. Now how do I literally tell the poor spongebob he needs to redo his code.
Am I missing something here? Please share your experience, how do you tackle this problem in a real world software house environment? If your fellow developer is on the next table , do you actually show them how to implement a certain method as they get stuck, or how do you deal with this situation?
thank you
Thanks
A good question. Of course i do not have the universal solution. Code documentation in msdn/sun style is a good base. But for concepts, architecture and so one you need more than this. In some projects we use wikis for that. For customer requests, we have a kind of ticket-system where we also store some (no-code) information to solution. All in all there is no central place for all the documentaion stuff.
Edit: Your code in self is often the best documentation, following clean code guidelines or something else is a real best practice :-)
Wikis are a cracking idea (good suggestion #Micha!). I used to use one in a previous company for a large engineering software/hardware project. It obviously spanned hardware and software guys and so it was a great way to share info across all teams. It's really useful if it's a long term project too - you can keep track of changes to functionality/API as things inevitably morph over time.
We used a paid service - Confluence if I remember rightly; but there are free wiki hosting sites too e.g. wikihost (just a quick google search, I can't vouch for them).
On another note though - have you thought about self documenting code at all? For example "Doxygen" or similar? Takes a lot of pain out of documenting every single function and also sets up a decent framework that can be padded out with more info where necessary. It also creates a nice UI for stepping through all the functions /class etc.
Edit: I've actually just started using Google Sites (sites.google.com) to create a wiki for a dev team I'm not working with. It's free (as in 'beer') and seems pretty good so far, although it does lack auto code formatting.
IMO you need both API documentation and plenty of examples.
You might get some mileage out of documenting your code of course, but if you're truly writing a system properly, your clients will never see your code. (That goes for clients in the calling sense, not necessarily in the "paying for your services" sense).
That's a fundamental of good practice and SOA, so you should really discard the "self documenting code" approach.
An alphabetic list of functions/methods/properties/whatever has value once the client has "got it" but until then, it's not immediately useful.
So that leaves you with having to showcase your creation. Give a bunch of immediately useful examples that demonstrate the kind of thing you envisaged. Make sure you have a simple example that demonstrates every function in its basic form with minimal interaction with the rest of the system (too many required interactions and you've probably not got a clean system anyway).
Once you have that, put it on a Wiki and encourage your users to enhance it. Consider using something interactive like a Stack-Overflow-like platform. MSDN is a good model but their examples often suck and can lack context. You might have the luxury of having more tight and specific uses than, say, the entire .NET framework. Early response to questions and updates to your examples/documentation will ensure your message gets across in the vital early days. This will help your documentation burden tail off quickly by looking after your clients and giving them useful, practical help.
Hope that helps.
In my projects I use a short description in my class files at the top, like:
//======
//
// modul: fileRunner.cs
// ...
// what: for playing audio/video
// depends on: consoleOutput.cs (Form)
//
//=======
#region HowToUse
//=======
//
// HowToUse
//
// 1. create instance of fileRunner:
// fileRunner p = new fileRunner();
// 2. run console program [progPath] with arguments [cmdsString]
// string output = p.RunExternalExe(progPath, cmdsString);
// 3. handle [output]
// if (output == "anyError"){do something;}
//
// [OUTPUT]
// "0" : process ended w/o errors
// "C" : canceled by user
// else: output is the string of the StdError, the called program submitted + StdOut after "Std output:"
//
// IMPORTANT
// Mention, this file depends on consoleOutput.cs to parse the output for gui.
// It doesn't support input ways, because the way ffmpeg is outputting doesn't allow it, it's not active
//=======
#endregion
For other classes I just named the public functions, that are self-describing.
An other option is to write on the top that they should look an the comment in the code and on the top of the public functions I use similar explanations:
#region convert an audio or video file from a drop
// FUNCTION: convertTo
// DOES: converting a file from a drop
// does not delete the original
// INPUT1: [path] as string,
// path to the destination file
// INPUT2: [e] as System.Windows.Forms.DragEventArgs,
// the args, the drop-object submits
// path of source file is in here
// OUTPUT: isConverted as bool,
// true if not (canceled or error raised)
public bool convertTo(string pWorkingFile, DragEventArgs e)
{
...
}
#endregion
If something changes you can mention it at the top too.
I think with SCM software it's a good option to mention the most important w/o wasting too much time on documentation.
as Stupid as it sounds, I would write him (Spongebob) a mail, or just tell him what he will need. If you already know who will need something in the near future, it is great if you can inform those peope before they strat to search and get headaches. Not everything in a project needs a technical Solution very often a human to human is much better.
Your documentation can also be in a wiki and then you can simply send Spongebob a link.
To reduce the pain involved in changing specifications over a large api, I'd suggest you follow the msdn/javadoc convention as mentioned earlier and also advice your team mate to use a modern IDE with autocompletion/autosuggest feature. Most of the common editors that provide auto suggestion also display documentation for the method/member to be used.
If you are seeking agile here, then docs and wikis are slight overkill; my 2 cents.
Why don't you just put your work in one git/svn project instead of working on the project parts independently? Then when you change a core function, you will see what it breaks and be responsible for fixing the methods that call it before committing your changes.
I am not a big fan of documenting extensively during development. It slows you down too much and you will have to redo it over and over again. Just create descriptive method names and be generous with you in-code comments.
For starters:
To help the situation between spongebob and yourself working together you will need some sort of Code Asset Management software (GIT, TFS, etc).
What if then I change GetWindow() to GetWindow(string title).. Now how do I literally tell the poor spongebob he needs to redo his code.
You should always start your day coding by "GET LATEST", meaning download code from the repository. If spongebob does this he will immediately see that he now needs to pass in string title as his code will stop compiling. It would be preferable that you literally tell spongebob that you have changed your code and he now needs to pass in a value, but if you are both checking in code every night and getting latest when you start coding for the day you should be both informed.
As far as the use of a WIKI or if you use Sharepoint doesnt matter. I would say to make it a little more efficient why not do this:
In your document repository (Wiki/Sharepoint) call the files by the page name so one is WordArt, the other is MainDocument, maybe one is PrintDocument (assuming these are different pages) and in the code you can simply put:
For more information on this visit the ___site at :http://yourrespositoryname.com/nameofprocedure
I've got an ASP.NET web application, that is essentially our intranet site. I made a lot of progress on the administration office's employee management pages. It ties into an SQL server database, and I'm using a three layered design (Objects, Logic, DataAccess). It was all reviewed and all of it was accepted, except! for the part that manages vacations and vacation histories.
My question, before I go into details is, how does one efficiently "untangle" code that is no longer necessary?
For example: previously I was treating each VacationDay as it's own entity with it's own history. Such that I could track the history of an individual day. To help in tracking, I have an enum called VacationDayAction, which includes options such as .Submitted, .RequestDenied, .CancellationRequested, and so on. This was in an attempt to provide meticulous detail for each day. It was then determined that we no longer need that. We do, however, still need VacationDays and all the basic functions of that (saving days, getting days, etc.), but now we no longer need any of the "history" related classes.
My problem is, when I right click a class that I no longer need in VS and go to "Show All References," I get a ton of results scattered across several pages. I need to get rid of all of them, without breaking the rest of the application. Is there not some kind of "smart" technique or method for easily untangling parts that are no longer necessary? This is particularly difficult because 90% of what I did was just fine, and needs to stay like it is. Yet scattered in that 90% is 10% of stuff that is no longer needed. I can't just go storming through with the delete key either, because with the removal of each reference, I need to be sure that any dependencies on that reference are also fixed in a way that they don't call stuff that isn't there anymore. And I still need the application is a compilable state, so that I can test along the way that the rest of the application didn't fall apart as a result of some deletion.
To give you an idea of my low level of experience, I started two years ago with having never used C#, ASP.Net, or Visual Studio. It blew my mind when, way after starting and as I was learning, someone taught me that I could use breakpoints. And then it really really blew my mind when I learned about multi-layered design. I'm wondering if there is not some technique or trick or feature that can help in scenarios like this, where you have to "untangle" and throw away unnecessary stuff.
This is not a simple question. In fact, I would say this is one of the major challenges for any systems developer; how to handle and get rid of old code which is not in use. There is lots of literature on this, and few really excellent answers. A good book may be "Working effectively with legacy code" by Michael Feathers, which deals with many related problems. It is no light read though, and will probably take some time to get through, but it will likely help you become a better coder, and better at these kinds of tasks in particular.
Maybe you can have a look at the Resharper tool? ( http://www.jetbrains.com/resharper/ ) It is a productivity tool which among other things shows "dead" code (unused code) in grey, and lets you remove it. It will also help you remove unused references from each class (again, they will be grayed out and let you remove them automatically).
Drawing diagrams where each major piece of code /component is a box with a line linking it to any related component might help you get a better overview; try to draw a hierarchy showing how different parts of the code are related and dependent.
The bottom line as far as I know, is that you just have to muddle through it, commenting out code a little at a time, then recompiling and testing it. If it still works, fine, now you can remove the commented out code completely. This would be easier if you had unit-tests covering your code, but I take it as a given that you don't, as is unfortunately often the case.
I'm looking for a rather arbitrary answer, so this might more be a discussion. I'm wondering what the best practise for commenting my C# code in visual studio is. Right now I'm using the triple /// to generate the xml and use sand castle to build a chm or html file. But my problem is that I use code comments for two reasons:
When other developers are using my code they can read the documentation, both intellisence and the chm. or html file.
But I also use commenting as reminders to myself. So I can remember my thoughts when I come back half a year later, to some complex methods.
How can both goals be accomplished without interfering with each other, and in the same time be a quick task, not taking a lot of coding time?
The best advice I can give you is:
Don't comment bad code; rewrite it!
If methods are very complex, most of the time you are doing something wrong (not always, but very close to always). Writing readable code is hard, but it pays of, because writing good comments that you (or your colleges) will understand a year later is hard as well (and perhaps even harder). Ways to make things clear is by breaking methods up in smaller well named methods and using very clear variable names.
A book that has helped me a lot in creating better code was Robert Martins Clean Code. If you haven't read it, please do. And let all the developers in your company read it.
Good luck.
Use /// comments to document your public and protected API. Use <remarks> to describe how your API should be used. The audience of these comments are other developers using your code.
Use // comments to comment your code whenever the code alone isn't adequate to fully understand what is going on. The audience of these comments are yourself perhaps three months out in the future or another developer going to maintain your code. You can use special comments like TODO or BUGBUG to flag codes you have to revisit.
I combine both commenting styles - /// for 'public' documentation on classes, methods, etc, and // on 'private' comments for myself or the coders that follow me to read.
I just had a conversation with my manager relating to checkin\out policies on a project I'm currently working on. Basically I tried to edit a file that was already checked out by another developer and I couldn't - I asked my manager why we couldn't edit the same class at the same time and he gave this reason for turning that functionality off: We had a lot of problems with developers editing the same Form (or anything visual done in the designer) and then cheking it in. Merging the changes in the designer generated code was a lot of hassle...
As I'm writing this I'm struggling to see what problem they were having - surely they were getting the latest code before trying to check something in??
Have any of you come across problems with editing the same Form (or something in the designer) as another developer and then checking into TFS? If so how did your team get around the problem? Did you also turn off the ability for developers to work on the same class?
EDIT: The following post (found here) is exactly the problem my manager was describing. Anyone know of a simpler way to resolve the issue than the ones in that post?
I would argue that the solution to your problem would be to establish best practices for source code modification.
Discourage people from going into UI code and arbitrarily jiggling the components around in the designer. Any reasonable UI modifications should be easily mergeable. Your best bet is to try and educate people as to the best way to merge in any given source control system. Also, as helpful as the designer is, ignorance of what code is being automatically generated in the background will be significantly detrimental in the long-term.
People who insist on locking checked-out files for the reasons you stated in your post typically wait long periods of time to check their code in. Naturally, the more time passes, the more code gets modified, so it makes merging difficult for these people. Checking in early, often, and incrementally requires people to think about their changes in stages, and for some coders, this is a rather painful cultural/psychological adjustment.
I've just checked back through the histories of some of my .designer.cs files and I can't see any changes that would cause a merge problems. There were no wholesale rearrangements of code for example.
Another thing to consider is to make sure that everyone does a "get latest" at regular intervals then any individual merge/resolution isn't going to be that great thus minimising the chances of anything going wrong.
It might also be worth investigating a 3rd party merge tool. There are plenty around.
Now it could be that the changes I've done are simple compared to the ones you've got so you should take my anecdotal data with a pinch of salt.
It can cause problems (in general) when a lot of people are editing UI concurrently. The merge logic will do a fine job merging things, but in a lot of cases the UI is drawn according to how things are added to the form. Your UI can get messed up quickly.
I don't know if I would use this as an excuse to enforce exclusive checkouts across the board, though. I might go from a (non programmatic) policy standpoint that says shared checkout for business logic, but exclusive for UI changes.
I would couple that with a strong MVP, MVC, or MVVM approach, though, which should limit the number of people that have to touch the UI concurrently.
As others have alluded to, keep one of the seminal rules of SCM in mind: merge early and often, and your problems are reduced. (along with that is "always get latest before you start working on the code).
Over the years as I have gone through school and been working in the industry I have often asked people for advice on commenting. Sadly, as we all know, commenting with many developers is something that is taken as a side note and not much else. With that said I usually get a fairly general answer. Really this does not help much to see what will really help as time goes on.
So, what do you think is the best way to structure C#, with Visual Studio, commenting?
At the very least, I would comment all parts of your public API, using a triple-slash XML comment block. This will make it easy to auto-generate documentation if and when the time comes.
Beyond that, I would comment any particular algorithms or pieces of code which are going to be hard to decipher in six months time. This 'selfish' approach to commenting (i.e. assume you'll have to maintain this code later) often leads to the best balance of ample documentation without overkill.
I try to follow some basic guidelines when writing comments.
Comments should be simple
Comments should provide clarity
Write documentation before you write implementation
Document why you're doing something, not what you're doing.
Use built-in (XML-style) comments for interfaces, methods, properties, and classes.
Provide a summary at the top of every file (e.g., Something.cs) with the file name, description, development history, and copyright information
Add comments for bug fixes (with bug number, if appropriate)
Make use of helpful annotations like //TODO //BUG and //BUGFIX
Don't comment out code unless you plan to use it
Add comments above the line(s) of code they apply to, not to the end of the line
Try to limit comments to a single line
Use // instead of /* */ for multi-line comments
Be clear--do not use "foo," "bar," etc.
Follow casing rules where appropriate (i.e., camelCasing and PascalCasing)
"Plenty and often"
--Bilbo, The Hobbit.
More seriously, comment things that are not obvious, and tell the reader what the goal of the code is, and perhaps why you chose it.
That's not going to change based on language.
Personally I use a combination of triple slash, SandCastle XML comments and inline comments for more complicated sections. Comment often but keep it concise, nobody needs to read reams of fluff before then can figure out what something does :-)