Learning about Hidden Features - c#

Today I found out about an interface I'd never heard of before: IGrouping
IEnumerable<IGrouping<YourCategory, YourDataItem>>
I am fortunate to have access to some of the best programming books available, but seldom do I come across these kinds of gems in those books. Blogs and podcasts work, but that approach is somewhat scattershot. Is there a better way to learn these things, or do I need to sift through the entire MSDN library to discover them?

Eric Lippert's blog. The real guts of C# - why there are some limitations which might seem arbitrary at first sight, how design decisions are made, etc.
Alternatively, for more variety, look at the Visual C# Developer Center - there's a whole range of blogs and articles there.
Oh, and read the C# spec. No, I mean it - some bits can be hard to wade through (I'm looking at you, generic type inference!) but there's some very interesting stuff in there.

The best place to start is Jon Skeet's C# Coding blog: http://msmvps.com/blogs/jon_skeet/
He regularly covers stuff you won't see anywhere else.

How about the Hidden Features series of questions?
Hidden Features of C#
Hidden Features of ASP.NET
And many more...

I personally like the way of discovering hidden features on my own while solving a specific problem. In the end, a hidden feature that you never needed to get something done is of questionable value. It just adds clutter to the brain.

The way to do it is to use the MSDN library to look things up. Then take a little time to look around what you found.
That's especially important with the pure API documentation. For instance, I just browsed to http://msdn.microsoft.com/en-us/library/system.xml.xmlreader.aspx (note how that URL is formed). When I look in the Contents pane on the left, I see everything from XmlDocument (and XmlDocumentFragment) all the way down to XmlReader. In the middle are some things I rarely or never use, like XmlNamespaceScope and XmlNodeOrder.
From time to time, spend a little time on "abstract knowledge". Sometimes, it's good to look up from the trees to learn your way around the forest. You never know when you'll need something you've learned to get you out of the woods.

For the people who don't know IGrouping:
http://msdn.microsoft.com/en-us/library/bb344977.aspx
I often read useful stuff on the Viual Studio Startup page and start clicking around to other keywords/areas. Not too promote StackOverflow too much, but you'll find some hidden gems here as well, simply by looking at how other people write code.
For example:
Hidden Features of C#?

Related

how to transition from C# to python?

i feel like i'm going back to the stone age.
how do i relearn to develop without intellisense (pydev intellisense doesn't count).. in general, how does one successfully leave the comfort of visual studio ?
I recently learned python with a strong C# background.
My advise: Just do it. Sorry, couldn't resist but I'm also serious. Install python and read: Python.org documentation (v2.6). A book might help too -- I like the Python PhraseBook. From there, I started using python to implement solutions for various things. Most notably, ProjectEuler.net questions.
It forced me to consider the languages and built in data structures.
Python is truly easy to use and intuitive. To learn the basics, took me about an hour. To get pretty good with it, took around 5 hours. Of course, there is always more to learn.
Also, I want to note that I would discourage using IronPython or Jython because I feel learning core, regular python is the first step.
Python has rich "introspection" features. In particular, you can find out a lot about built-in features using a command called help() from the Python command line.
Suppose you want to use regular expressions, and want to find out how to use them.
>>> import re
>>> help(re)
You get a nice display of information, automatically shown to you a page at a time (hit the space bar to see the next page).
If you already know you want to use the sub() function from the re module, you can get help on just that:
>>> help(re.sub)
And this help() feature will even work on your own code, as long as you define Python docstrings for your modules, classes, and functions.
You can enable features in the vim editor (or gvim, or vim for Windows) that enable an "IntelliSense"-like autocompletion feature, and you can use Exuberant Ctags to generate hyperlink "tags" to let you navigate quickly through your code. These turn vim into something that is roughly as powerful as an IDE, with the full power of vim for editing. (There isn't an explicit refactoring tool built in to vim, but there are options available.
And as others have noted, you can get IDEs for Python too. I've used the Wingware IDE, and I recommend it. I try to do most of my work with free, open-source software, but that is one piece of proprietary software I would be willing to buy. I have also used Eclipse with the Pydev plugin (I used its refactoring tool and it worked fine).
P.S. Python has a richer feature set than C#, albeit at the cost that your code won't run as fast. Once you get used to Python, you won't feel like you are in the stone age anymore.
One step at a time?
Start off with simple programs (things you can write with your eyes closed in C#), and keep going... You will end up knowing the API by heart.
<rant>
This is sort of the reason that I think being a good visual studio user makes you a bad developer. Instead of learning an API, you look in the object browser until you find something that sounds more or less like what you are looking for, instantiate it, then hit . and start looking for what sounds like the right thing to use. While this is very quick, it also means it takes forever to learn an API in any depth, which often means you end up either re-inventing the wheel (because the wheel is buried under a mountain worth of household appliances and you had no idea it was there), or just doing things in a sub-optimal way. Just because you can find A solution quickly, doesn't mean it is THE BEST solution.
</rant>
In the case of .NET, which ships with about a billion APIs for everything under the sun, this is actually preferred. You need to sift through a lot of noise to find what you are aiming for.
Pythonic code favors one, obvious way to do any given thing. This tends to make the APIs very straight forward and readable. The trick is to learn the language and learn the APIs. It is not terribly hard to do, especially in the case of python, and while not being able to rely on intellisense may be jarring at first, it shouldn't take more then a week or two before you get used to it not being there.
Learn the language and the basic standard libraries with a good book. When it comes to a new library API, I find the REPL and some exploratory coding can get me to a pretty good understanding of what is going on fairly quickly.
You could always start with IronPython and continue to develop in Visual Studio.
The python ide from wingware is pretty nice. Thats what I ended up using going from visual studio C++/.net to doing python.
Don't worry about intellisense. Python is really simple and there really isn't that much to know, so after a few projects you'll be conceiving of python code while driving, eating, etc., without really even trying. Plus, python's built in text editor (IDLE) has a wimpy version of intellisense that has always been more than sufficient for my purposes. If you ever go blank and want to know what methods/properties and object has, just type this in an interactive session:
dir(myobject)
Same way you do anything else that doesn't have IntelliStuff.
I'm betting you wrote that question without the aid of an IntelliEnglish computer program that showed you a list of verbs you could use and automatically added punctuation at the end of your sentences, for example. :-)
I use Eclipse and PyDev, most of the time, and the limited auto-completion help that it provides is pretty useful.
It's not ever going to come up to the level of VS's IntelliSense, and it can't, because of the dynamic nature of Python. But there are compensations, big ones.
The biggest is the breaking of the code-compile-test cycle. It's so easy to write and test prototype code in IDLE that very often it's where I go first: I'll sketch out and test a couple of methods that have to interoperate, figure out that there's something I don't know, learn it, fix my test, and then port the whole thing over to PyDev and watch it work the first time.
Another is that it's a lot simpler. It's really important to know what the standard modules are, and what they do, but for the most part that can be picked up with a little reading. I only use a small handful of modules in my everyday programming - itertools, os, csv (yeah, well), datetime, StringIO - and everything else is there if I need it, but usually I don't.
The stuff that it's really important to know is stuff that IntelliSense couldn't help you with anyway. Auto-completion isn't going to make
self.__dict__.update(kwargs)
make a damn bit of sense; you have to learn what an amazing line of code that is, and why you'd write it, by yourself.
Then you'll think, "how would I even begin to implement something like that in C#?" and realize that the tools these stone-age people are using are a little more sophisticated than you think.
A mistake people coming from C# or Java make a lot is recreate a large class hierarchy like is common in those languages. With Python this is almost never useful. Instead, learn about duck typing. And don't worry too much about the lack of static typing: in practice, it's almost never an issue.
I'm not too familiar with Python so I'll give some general advice. Make sure to print out some reference pages of common functions. Keep them by you(or pinned to a wall or desk) at all times when your programming.. I'm traditionally a "stone age" developer and after developing in VS for a few months I'm finding my hobby programming is difficult without intellisense.. but keep at it to memorize the most common functions and eventually it'll just be natural
You'll also have to get use to a bit more "difficult" of debugging(not sure how that works with python)
While your learning though, you should enjoy the goodness(at least compared to C#) of Python even if you don't have intellisense.. hopefully this will motivate you!
I've only ever used IDLE for python development and it is not fun in the least. I would recommend getting your favorite text editor, mine is notepad++, and praying for a decent plugin for it. I only ever had to go from Eclipse to Visual Studio so my opinions are generally invalid in these contexts.
Pyscripter does a reasonable job at auto-completion/intellisense. I've been using it recently as I started to learn Python/Django, where I've been mainly a C# developer for the last few years.
I suggest going cold turkey - languages like Python shine with great text editors. Choose one you want to become amazing at (vim, emacs, etc.) and never look back.
I use Komodo Edit and it does reasonably good guessing at the autocompletion.
Others have suggested several editors that have intellisense-like capabilities. Try them out.
Also install ipython and use that to learn the language interactively. It is like a souped up version of the regular python interactive shell with lots and lots of added capabilities, and one of the most useful it its extensive context sensitive tab-completion and help.
For example if you type
import r<tab>
it will show all the modules you can import starting with r
import re
re.<tab>
will show all the objects in the re module
re.compile?
will show the docstring and other information about the re.compile function, automatically piping it through a pager if it is longer than a screenful.
re.compile??
will show the source code as well, if available.
Using this I find it is much faster to switch to ipython and query objects directly than it is to look up anything in the docs. You have access to the usual python help() system as well.
ipython has lots and lots of other features - far too many to cover in a short post.

What C# knowledge should I have? [closed]

Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 11 years ago.
Improve this question
A very open question. I've been programming in C# for the
past 5 months doing small projects that I completed
successfully.
Today I went to an interview for a C# role. The 1st question
was 'Tell me about boxing'. Given my experience I had no
idea what the guy meant. Needless to say the interview
didn't go that well. Others questions were 'why isn't it
recommended to use an ArrayList of int', 'tell me what you
know about threading', etc.
I don't really want this to happen again so I'm planning to
spend some time reading (and practising) more on C#. I
understand that the best way of learning is by coding but
coding wouldn't have really helped me answer the question
about 'boxing' for example.
I'm not asking you to answer the above technical questions.
In fact, I know now their answer as I went straight to
Google after the interview and it's how I realised that my
C# knowledge is somewhat limited.
My question is: in your opinion, which knowledge should any
C# developer have? Ideally it would be better if you could
categorize it (Basic knowledge anyone should have without
exception, Advanced knowledge, Expert knowledge etc). No need
to go into details. Doing research on whatever you list will
be a good exercise for me.
I would expect someone going for a professional C# job to know about:
Generics and generic collections
Interfaces (general)
Interfaces (specific), namely -
IDisposable: how it's integrated into the language and why
IEnumerable: including common extension methods, iterator blocks, and deferred execution
Overview of serialization in .Net (maybe not have done it, but understand what it is and know where to look in the namespace heirarchy and documentation)
Overview of Xml in .Net (same as serialization)
Overview of threading concepts (same as xml/serialization). Bonus points for understanding why most thread-safe collections aren't.
Have used anonymous delegates / lambdas in at least one project, and therefore also have a basic idea about closures.
Comfortable explaining some basic concepts from at least one of winforms, wpf, webforms, or MVC
Be able to answer some easy questions on specific common classes in the .Net BCL: namely from System.Data (think parameterized queries!) and System.IO (filestreams, path).
Garbage collection: when should you call GC.Collect (hint: pretty much never) and why
Here is a good list: What Great .NET Developers Ought To Know.
My personal experience from a long time ago when I was in school.
I went to see my father at work in a bank. At that time, most of his day was taking care of accounts and making sure every thing worked. What I saw was he was trying to tally/calculate large numbers and calculating(basic additions/multiplications...).
After noticing him, I asked him: Dad, if all you have to do is basic additions and multiplications, why bother to study till graduation?
His response was : While you don't have to use all the knowledge you have acquired, that knowledge would help you make learned decisions.
Coming to your question: While you dont have to use the entire set of concepts, knowing that they exist would help you make good decisions while you code.
My suggestion along with the others posted would be to try and spend some time on stackoverflow every day.
Good luck.
A good interviewer isn't going to grill you on trivia. That's why we have Google. A good interviewer is going to find areas you don't know, and ask you questions there, as that's the best place to find out how you react when confronted with something you don't have down pat.
The best advice I can give for interviews is to not worry about the technical trivia too much. Instead, in an interview, focus on problem-solving skills. If you don't know something, don't try to hide it, just admit it. If you think you know, it's okay to say "I'm not sure, but I think it's this." And don't get flummoxed either - at that point, usually the interviewer will give you a hint. This is not just giving you the answer, it's another part of the test - to see if, given a nudge in the right direction, you can extrapolate from there.
For the boxing/ArrayList/int questions, if I was interviewing and you didn't understand boxing, I'd give you a basic description of what boxing did. Then I'd ask you, knowing what I just told you, why you might think using ints in an ArrayList might be a bad idea.
One thing that will go far in any interview is focusing on the requirements, the desired result, and boundary conditions or edge cases. As most programming interview questions fall into the "write this method" category, make sure you get the following correct:
1) The inputs to the method
2) The expected output of the method
3) Boundary and edge cases.
This sounds ridiculously basic, but it's amazing how many developers, even ones with experience, don't bother thinking through these things. Code solves a problem - if you don't understand the problem correctly, you can't solve it correctly.
I would have to say that if an interviewer can be fooled into thinking someone has more .NET / C# experience by he or she visiting a webpage, then the interviewer is failing. I've interviewed a number of people myself, and I really like the approach of giving them some easy to understand problem to solve, and asking them to write some code on a white board. Even if they've memorized the answers to every question on Scott Hanselman's blog, I would learn a lot about how comfortable they are in the language, as well as how they go about problem solving. I'm looking for a developer, not a partner for Trivial Pursuit, .NET Developer Edition.
That said, keeping up with blogs like Hanselman's is a fantastic way to keep up with the jargon. You could code C# in a vacuum for years, fully understand the advantage of a strongly-typed List<int> over ArrayList, but never actually use the term "boxing". But it's much more time consuming in an interview to ask, "Describe the advantage of iterating through a List<int> instead of an ArrayList of int," than it is to ask, "Tell me about boxing." Plus, actually researching the answers to Hanselman's .NET interview questions (especially if you explore the details and ask "Why?") will make you a better developer. So by all means, keeping reading Hanselman.
And one more note... If I ask someone whether a String is a reference type or a value type, and they simply say "Hmmm... Reference type," I'm not going to be nearly as happy as I would if the response was, "Hmmm... Reference type, but that's an interesting question." "Why is that?", I say... "Because string is implemented so that the string is immutable, allowing you to do things with it like safely use it as a hash key. Or pass it to a method, knowing the value cannot be changed. So in a way, strings can act a lot like value types..." And that would be a great conversation, leading me to ask, "So tell me more about why hash keys should be immutable..."
It's not just the difference between answering a 50/50 question correctly and all the additional information in the second answer. Having an intelligent conversation with a interviewee leads me to think I'll have intelligent conversations like that on a regular basis once the interviewee becomes my coworker. And that's something I'm definitely looking for.
Also depends on the role. If this was advertised as a jnr role then a threading question is a little tough...sometimes agencies/employers have unrealistic expectations.
A similar thing happened to my significant other taking a driving test. The state trooper said, "make a roundabout" and she didn't know what he was talking about. Both of us think a roundabout is a type of road layout with a big circle, not a u-turn as the instructor meant. So I know what you mean.
Programming job interviews vary wildly. Some people think you can't really judge a programmer well in an interview and are willing to give anyone who makes a good impression a chance. Others are grueling things which only those overqualified for the position would pass, and you will probably be suprised how often you get a call back from those.
This is something I have been pondering myself a lot lately. Using C# plenty but not sure what I am missing.
I ordered
Microsoft® .NET Framework Application Development Foundation
Which covers a lot of ground related to C#
Also looking at C# in Depth
Read some of this already. Has some great information from a high quality author.
In depth is on sale too via Jon Skeet's blog

artificial intelligence - Creative Writing

I am trying to find information (and hopefully c# source code) about trying to create a basic AI tool that can understand english words, grammar and context.
The Idea is to train the AI by using as many written documents as possible and then based on these documents, for the AI to create its own creative writitng in proper english that makes sense to a human.
While the idea is simple, I do realise that the hurdles are huge, any starting points or good resoueces will be appriacted.
A basic AI tool that you can use to do something like this is a Markov Chain. It's actually not too tricky to write!
See: http://pscode.com/vb/scripts/ShowCode.asp?txtCodeId=2031&lngWId=10
If that's not enough, you might be able to store WordNet synsets in your Markov chain instead of just words. This gives you some sense of the meaning of the words.
To be able to recompose a document you are going to have to have away to filter through the bad results.
Which means:
You are going to have to write a program that can evaluate if the output is valid (grammatically and syntactically is the best you can do reliablily) (This would would NLP)
You would need lots of training data and test data
You would need to watch out for overtraining (take a look at ROC curves)
Instead of writing a tool you could:
Manually score the output (will take a long time to properly train the algorigthm)
With this using the Amazon Mechanical Turk might be a good idea
The irony of this: The computer would have a difficult time "Creatively" composing something new. All of its worth will be based on its previous experiences [training data]
Some good references and reading at this Natural Language article.
As others said, Markov chain seems to be most suitable for such a task. Nice description of implementing Markov chain can be found in Kernighan & Pike, The Practice of Programming, section 3.1. Nice description of text-generating is also present in Programming Pearls.
One thing, though not quite what you need, would be a Markov chain of words. Here's a link I found by a quick search: http://blog.figmentengine.com/2008/10/markov-chain-code.html, but you can find much more information by searching for it.
Take a look at http://www.nltk.org/ (Natural Language Toolkit), lots of powerful tools there. They use Python (not C#) but Python is easy enough to pick up. Much easier to pick up than the breadth and depth of natural language processing, at least.
I agree, that you will have troubles in creating something creative. You could possibly also use a keyword spinner on certain words. You might also want to implement a stop word filter to remove anything colloquial.

Do you have any good advice/links to a set of coding standards or best practices to follow?

For those of us that have programmed enough I’m sure we have come across many different flavours of coding standards that you can use when it comes to programming.
e.g. http://msdn.microsoft.com/en-us/library/ms229042.aspx
You might derive your coding standards for the current company you work for or from the original author of the code you’re working on. Coding styles are often used for specific program languages and some styles in one coding language might not be considered appropriate for others. Of course some coding standards can be applied across many different program languages.
Thank you for your time.
EDIT: As we know there are many related articles on this subject, but C# Coding standard / Best practices in SO has some very useful links in there which is worth a visit. (Check out the 2 links on .NET/C# guidelines by ESV - Accepted Answer)
Google has a posted style guide for C++ here which I consult sometimes. Just reading through the explanations and reasoning, despite whether you end up agreeing with some of the styles or not, may teach you some things you might not have thought about.
My best advice regarding coding standards: don't let them get in the way when trying to get work done.
A big bureaucracy might actually hinder progress in projects instead of helping to achieve better team work. When people complain about not following coding standards instead of the actual quality of the code, then it is too much regulation.
Other than that, pick one from the many suggestions and try to stick with it for as long as possible to build a code base following a single standard that you are used to.
Coding standards are good, but coding standards written from scratch in which the company reinvents the wheel, or coding standards imposed by a single "prophet", can be worse than having no coding standards at all.
This means:
Coding standards should be discussed and agreed upon.
The coding standards document should include the reasons behind each rule.
Coding standards should be at least partially based on reliable sources.
The sources I know of for the languages in your tags are:
For C++: The book C++ Coding Standards by Sutter/Alexandrescu.
For C#: 4 or 5 PDF's I found googling for C# Coding Standards :)
Adam Cogan has a great set of rules on his web site. There are coding guidelines, but there is much more there also.
Adam Cogan's Rules to Better...
Coding standards are great. We've been using Lance Hunt's C# Coding Standards for .NET almost without modifications
If you are maintaining code that continue to use the same standard as the original code was developed in (there is nothing worse then trying to debug a problem when the code looks all higgildy piggeldy)
Some comment to the post suggesting looking at the Google C++ guidelines. Detailed discussion about some aspects of these guidelines are posted at comp.lang.c++.moderated.
Some weird or controversial points include:
We don't believe that the available
alternatives to exceptions, such as
error codes and assertions, introduce
a significant burden.
As if assertions were a viable alternative... Assertions are usually for programming errors and situations that should never happen, while exceptions can happen (are somewhat anticipated) in the execution flow.
Reference Arguments: All parameters
passed by reference must be labeled
const. ... In fact it is a very strong
convention that input arguments are
values or const references while
output arguments are pointers.
No comment, about weasel phrase a very strong convention.
Doing Work in Constructors: Do only
trivial initialization in a
constructor. If at all possible, use
an Init() method for non-trivial
initialization.  ... If your object
requires non-trivial initialization,
consider having an explicit Init()
method and/or adding a member flag
that indicates whether the object was
successfully initialized.
Yes... 2-phase init to make things simpler... What if I have const fields? This rule is probably the effect of attitude towards exceptions.
Use streams only for logging
Which streams? IOStreams, standard C streams, other?
On one hand they advise to use macros only in exceptional situations, while they recommend using DISALLOW_COPY_AND_ASSIGN to prohibit copy/assign. They could have advised the approach with special class (like in Boost)
Do not overload operators except in rare, special circumstances.
What about assignment, or arithmetic operators for numeric calculations, etc?
Default parameters are more difficult to maintain because copy-and-
paste from previous code may not reveal all the parameters. Copy-and-
pasting of code segments can cause major problems when the default
arguments are not appropriate for the new code.
The what? Copy/paste from previous code?
Remember that reading any of the guidelines can introduce a bias to your way of thinking. And sometimes it won't be beneficial for you or your code. I agree with some other posts advising reading good books by good authors beforehand. When you have sufficient amount of knowledge, then you are able to look at the guidelines and find good and weak points easily, without creating a mess in your brain ;)
If you plan to introduce a code-formatting standard to an existing programming team, get input from each member of the team so they'll have "buy in" and be more likely to write code to that standard.
Programming styles are as difficult to change as habits, and you'll have to accept that some people won't make their code 100% compliant 100% of the time. It would be worth your time to find (or write your own) pretty-printer program and periodically run all your code through it to enforce consistency. (I always felt uneasy when manually checking in source code changes that only consisted of formatting corrections for other peoples' code; I worried that others would label me a nitpicker.)
Sun Java Code Conventions
Python Style Guide
Zend Coding Standard for PHP
Having asked this question. I found that the accepted answer proved to be sufficient for my needs.
However, I realise that this is not a 'one-size-fits-all' scenario, so there is a large quantity of information within the thread that you may find more or less useful. Weel worth a read!
For Java and other C-family languages I recommend Sofware Monkey's coding standards (of course, since they're mine).
In general, keep them simple, and provide examples and justification for every requirement.
What's in the standard doesn't really matter all that much. What matters is that you have one, and that your developers follow it.
It doesn't quite answer the question, but it's worth a mention...
I read Steve McConnell's Code Complete. Whilst it doesn't give you a pre-baked set of coding standards it does set out a lot of good arguments for the various approaches. It'll make you think about things you'd not thought of before.
It changed my little world for the better.
Coding standards themselves are great and all, but what I think is much, much, MUCH more important is keeping with the style of whatever code you're maintaining. I've seen people add a function to some class written one way and forcing their coding standard on just that function. It's inconsistent, it sticks out, and, in my opinion, it makes it harder to enjoy the class "as a whole".
Whenever you're maintaining code, look at the code around it. See what the style is. K&R braces? Capital Camel Case methods? Hungarian? Double-line comment blocks between every function? Whatever it is, you should do it too in that specific area.
Before I leave, one thing I'd like to note that's related - naming files. I'm mainly a C++ guy, so this may not apply to whatever else, but basically it goes _.h or .cpp. So, Foo::Bar would be in Foo_Bar.h. Common things (i.e. a precompiled header) for the Foo namespace would be in Foo_common.h (note the lowercase common). Of course, that's a taste thing, but everybody who has worked with this has come out in favor of this.
i think Code Craft - The Practice of Writing Excellent Code pretty much sums it all up
Very popular are Ellemtel rules for C++.
For C# I recommend Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) (Microsoft .NET Development Series).
Mono Coding Guidelines
The answers here a pretty complete, thus I am not pointing to another coding standard document. However, once you decided to stick to one style you should use an automated coding style enforcer throughout your team.
For Java there is checkstyle and for .NET Microsoft Style Cop.
Here is a similar discussion on Stackoverflow: C# Coding standard / Best practices
Camel and pascal casing alone solves a lot of coding standard problems

What do you think is the best C# Commenting Structure? Specifically with Visual Studio

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 :-)

Categories

Resources