Related
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.
Sometimes to make a variable/method/class name descriptive I need to make it longer. But I don't want to, I'd like to have short names that are easy to read. So I thought of a special addin to IDE like Visual Studio to be able to write short names for class, method, field but be able to attach long names. If you need to - you can make it all long or you can make single name long. If you want to reduce it - use reduction, like two views of the same code. I`d like to know what others thinking about it? Do you think it is usefull? Would anybody use the kind of addin?
Why not just use the standard XML commenting system built into Visual Studio.
If you type /// above the Class/Method/variable etc, it creates the comment stub.
These comments popup through Intelisense/Code Completion with extra info.
This way you keep your naming conventions short and descriptive whilst commenting your code.
You can run a process to then create documentation for your code using these comments.
See: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx
A variable name should be as long as required to make it identifiable, does it matter if it's a bit longer than you would prefer? As long as the code is readable and understandable, surely this makes no difference?
Use comments for names that would be far too long to use as a variable/class name. This would be a lot more appropriate.
If a method name is too long, then it shouldn't be a single method...
I wouldn't use an addin like that.
I never worry about long names. If a method name becomes too long, it may also indicate that the method does too much (unless it happens to include a really long word). On the other hand, I also try to avoid repeating myself. I would not have Account.AccountId for instance, but rather Account.Id. I also lean back on the namespace; if the namespace is clear about what domain I am in, I usually try to not repeat that in class- or member names.
Bottom line; I can't see myself using such an addin.
Other programmers without this addin would find themselves in trouble because if you give too short names they will not fully understand the code, if you give long names they will loose time reading and eventually get angry because long names are difficult to remember :P
One has to find the best name for everything one writes, imho there is no need for a switch to turn on and off verbosity for identifiers.
I would not use that addin.
Nor I. The fact is you are talking about VisualStudio. It takes the heavy-load of remembering most variables names (long and short) with IntelliSense. As Power said, as long as the code is readable and understandable, that's all that matters.
With ReSharper 4 and above, you can get automatic expansion of type and variable names that are camel or Pascal cased:
(source: jetbrains.com)
So you could call your variable myExtremelyLongAndDescriptiveVariableName but then just type mELADVN to use it.
I don't think I'd want it.
The overhead of switching between different views would be as much work as hitting F12 and reading the comment for the function, which will always be more descriptive than the long name.
I wont.
Long function names could be handy in somecases. If you have a special case or something.
Some examples:
what would you favor for multiplication, mul or multiply ? multiply is my choice
Choosing functionnames is a matter of making your code clear for using, if you have too small names and you have to read comment to know what the function does, then youre doing it wrong
IDEs, text editors and compilers support limited (if at all limited) form of described functionality - that is source code comments. I think comments do very well and don't see any necessity of described addin. If comments are too long they can be folded. If you need source code with no comments you can easily strip them off with regex of similar stuff.
Id like to have short names that are
easy to read.
That is often a contradiction in terms.
Take for example a name like oScBf, if you don't already know what it's for it's practically unreadable. Is it outputScreenBuffer, onlineSourceBitflag, openScannerBrowsefile, outdoorSpecialBikinifavorites...?
Longer identifier names are usually preferrable. Eventhough it's more to read, it's still easier to understand.
Reading code is in some ways similar to reading text. You expect it to follow a certain pattern to be easy to read, if you start to add a lot of abbrev. and non-std words in da text u hav 2 stop n think what it means, and u lose da flow. :)
It's a bad idea. Variable names don't usually need to be long to be adequately descriptive, you'll waste a lot of time writing two versions of every name, and many programmers will probably find it rather confusing to have multiple names for the same thing.
With XMLDoc and intellisense help, you can add any extra detail required to fully describe a code element - the name doesn't need to describe the minutiae, only give a clear and distinctve idea of what the code element's purpose is.
With name auto-completion readily available, there is no longer any reason to complain of long names requiring lots of typing.
Also, good coding style is all about making code easy to read, understand and maintain, not about packing more code into a smaller space.
OO design should help to break functionality down hierarchically into namespaces and classes, reducing the need for such long names at the class/method level)
Lastly, if you really must shorten names, most languages most languages provide easy ways to strip off namespaces and/or add competely new aliases for names (e.g. 'typedef' and 'using' in C++, 'using' in C#), so in a localised region you can easily refer to a long name via a shortened variant or alias if you wish.
I like the idea. It's really good and I congradulate you and hope you're successful in developing it. Although I would never use such an Add-On.
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#?
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
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 :-)