As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
what tokens do you find useful in visual studio?
(visual studio 2010 → environment → task list → tokens)
currently i have only:
HACK - low
REVIEW - high
TODO - normal
WTF - high
(only these - deleted some default ones)
are you using any others?
are you covering any other important thing with comment tokens?
any best practices? thnx
Here's the ones I use:
TODO: the functionality is not yet implemented
FIXME: the code should be modified/refactored to achieve some goal (higher maintainability, better performance, and so on)
BUG: the code has a known bug
I've done a combination of most of the above tokens.
RED: code that simply does not work / compile
// Error - This code is throwing a specific reproducible error.
// Broken - This code is broken and will not run.
// WTF - WHAT THE FRIG.
ORANGE: code that works but is not right
// Hack - This code has intentionally been hacked in order to work. Should not go into production.
// FixMe - This code works but could be better. Needs better abstraction, maintainability, performance, etc.
// Bug - This code works and was expected to be right but a bug has been found. (usually flagged post production)
// Review - This code is probably right but should be reviewed for piece of mind.
// Smells - Same as FixMe
BLUE: code that works but either needs more features or more explaining
// Todo - Functionality is not yet implemented
// Note - Better explain what's going on. This is gives a higher profile to standard comments, and allows notes to be found in the to-do pane.
I like the Token REMOVE, indicating that it's only in for testing, and should not be included in the final release
Another built-in is NOTE.
Vim automatically highlights XXX, which happens to be my token of choice for the ease of typing it.
Sun's (old) Java coding conventions have this to say:
Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I am teaching an upper-division software engineering course and am reviewing every student's code. Some of my students have picked up the habit elsewhere of adding a comment to the right of every closing brace identifying the statement type, such as:
if (x > 3) {
y = 10;
} //if
I have told the students to follow the Android code style guidelines, which says nothing about this practice. On what grounds should I tell them not to do this (besides personally not liking it), or should I permit it?
Comments are for clarifying code and increasing readability. It's clear enough to most reasonable software developers that the statement is an "if." Furthermore, many IDEs and editors automatically highlight brackets such as these, so the comment isn't necessary. Generally, you should save comments for describing what methods, classes and variables do (e.g. in Javadoc), or what subroutines within a method will do. This is based on the general guideline of making sure everything you add improves the code.
Tell them that they should assume that person who review code knows language syntax and how to program. Comments should be rare, indicate and explain some weird and not obvious code section (for instance the api provided by some library is bugged and some workarounds/hacks are needed). We've got documentation (and unit tests) to explain how to use and how code should behave. For educational purpose you can write small class/module filled with such "comment-documentation", give it to students and ask them what did they learn about code from these comments.
Well, most likely this will end up in a discussion based on personal preference - which is not within the scope of stackoverflow. But aI'll answer anyway:
In my opinion, that's a bad thing to do - for multiple reasons.
It messes up the code. the more comments are in there, the less readable it is. A single } in a line tells me, instantly, that the last block ends here. with the comment behind, there is more to read - and no additional info (but people will read anyway, cause they don't know that the comment doesn't include any info... and because people tend to read everything automatically)
It leads to sloppy indentation. After all, that may even be the reasons people started that in the first place.
it's unnecessary - if I indet the code in a consistent manner, it shouldn't be necessary to note what was closed, it should be easily visible by just going up to where the last statement with the same indentation level was. In most cases (unbless you're reverse-indenting (or whatever that is called), which I don't like at all) this should be very easy, as there is nothing in between...
it leads to bigger file sizes. may be invalid on modern systems, but still.
Every time is overkill. It depends on the level of indentation and the length of your function, but these are usually signs that you need to step back and refactor. The only time I explicitly do it is for namespaces in C++
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
I already seen this one Why are there so many slightly different ways to do the same thing in Ruby? but it doesn't help a bit. Having multiple slightly different semantics and syntax for the same thing is IMHO confusing and counterproductive. I was trying to find some spec, or rationale on why this is so, but they're nowhere to be found (unlike Java and Python where every language feature is well documented with motivation etc.).
It's not just String, it's everything. What I'm looking for is a generic explanation on why the japanese think that having 100 ways to do the same thing is better than one explicit way. Remember that we're talking about programming language, that's not a musical instrument, or a paint brush, it's a tool to get the job done and have fun along the way. It's not fun to read some code and wonder why she used %<hello kitty> instead of "hello kitty", especially when you're looking for a bug.
I see the benefit in standardization, which is a related concept. I hope everyone else does. Why doesn't Ruby support some 100 versions of customized HTTP protocol, for the same reason they support 100 ways to create a String?
The reason there's many different ways to create a string is because there's many reasons you might need a string. Since strings are the backbone of many applications, it makes sense that this facility is robust and varied.
Once you're used to it, you'll find the rigid quotation systems in other languages to be more of a nuisance than anything. HTML often requires using both single ' and double " quotes for embedded JavaScript or other attributes, and unless you want to render your string into unreadable pulp by spiking in backslashes \ before any of them you'll be better off with the %q[ ... ] type method of quoting.
Any good toolbox has a variety of tools. Don't complain that your wrench set is confusing because it has so many different sizes of wrench. Sometimes you'll need a specific one, and then you'll be grateful. Many of these methods have been borrowed from languages like Perl, and Perl is inspired by other things like bash.
Typical use cases:
double_quotes = "typical use case with #{variables}"
single_quotes = 'strict string literals'
alternate_double_quotes = %Q[<for html="tags('with both quotes', 'and #{variables}')">]
alternate_single_quotes = %q[<for html="tags('with both quotes')">]
inline_string = <<END
Useful for long blocks of freeform
text such as sample data or templates.
END
I've found that the %q[ ... ] method comes in handy when trying to express multi-line strings that contain quotes as is often the case with SQL:
execute(%q[
INSERT INTO examples (id, feature_code)
SELECT id, CONCAT('example_', feature_code)
FROM things
GROUP BY foo
ORDER BY bar
])
It is relatively easy to spot [ ... ] pairings but not as easy when you have many escaped quotes. It's easy to miss a closing quote unless you have a syntax highlighting editor.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 12 years ago.
Personally I can't stand region tags, but clearly they have wide spread appeal for organizing code, so I want to test the temperature of the water for other MS developer's take on this idea.
My personal feeling is that any sort of silly trick to simplify code only acts to encourage terrible coding behavior, like lack of cohesion, unclear intention and poor or incomplete coding standards.
One programmer told me that code regions helped encourage coding standards by making it clear where another programmer should put his or her contributions.
But, to be blunt, this sounds like a load of horse manure to me. If you have a standard, it is the programmer's job to understand what that standard is... you should't need to define it in every single class file.
And, nothing is more annoying than having all of your code collapsed when you open a file. I know that cntrl + M, L will open everything up, but then you have the hideous "hash region definition" open and closing lines to read.
They're just irritating.
My most stead fast coding philosophy is that all programmer should strive to create clear, concise and cohesive code. Region tags just serve to create noise and redundant intentions.
Region tags would be moot in a well thought out and intentioned class.
The only place they seem to make sense to me, is in automatically generated code, because you should never have to read that outside of personal curiosity.
I like regions, and use them all the time. I use them to group members of the same kind inside classes.
You already have the means to collapse methods, classes and namespaces in the editor. Regions give you an option to create another level that lets you arrange the code in a way that corresponds to what you think is important.
StyleCop doesn't like regions:
SA1124: DoNotUseRegions
Cause
The C# code contains a region.
Rule Description
A violation of this rule occurs whenever a region is placed anywhere within the code. In many editors, including Visual Studio, the region will appear collapsed by default, hiding the code within the region. It is generally a bad practice to hide code, as this can lead to bad decisions as the code is maintained over time.
How to Fix Violations
To fix a violation of this rule, remove the region from the code.
There is some discussion about whether or not this is a reasonable rule.
The consensus seems to be that some people like regions and some people don't - it is up to individual teams to decide. The most important thing is to use a consistent style throughout your project.
One place where regions might be acceptable is to group all the methods that implement a particular interface. It is worth noting that Visual Studio automatically adds a region if you use the code generation feature to provide method stubs for implementing an interface.
The only place they seem to make sense to me, is in automatically generated code, because you should never have to read that outside of personal curiosity.
The partial class feature is better for separating automatically generated code from manually generated code within the same class.
When working with automatically generated source, code can be added to the class without having to recreate the source file. Visual Studio uses this approach when it creates Windows Forms, Web service wrapper code, and so on. You can create code that uses these classes without having to modify the file created by Visual Studio.
I think that #region is perfectly fine. I've never used it myself, but if you have a large or complex class, it can help with finding what you're looking for. Imagine if you're implementing ID3D10Device1- that's over a hundred methods to implement. You want to just throw them all in one place?
I do use regions to organize bigger constructs in a class, ie. a Dependency Property with callback and methods getting called by this, eg. you have a DP that takes an IEnumerable<T>, and you want to use the weak event pattern to respond to INotifyCollectionChanged. This can take some code, and as I won't be touching it after coding it, I put it in a region.
However, if you resort to regions to structure your logic, this is severe code smell and that's what the StyleCop rule in Mark's post is pointing hat.
while I am programming I use regions a lot they help me keeping my code organised and be able to focus only on parts I care. I always add comments on the regions and what are they about .But when I am done I am always removing them. Its a handy tool, that's all.
IHMO, if you have #region section in a class, it means that you have two behaviors in your class and so you should split your class in two objects.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Foundations of F# and Expert F# are probably the two most prevalent books used to learn f#.
Both were written at the time of the 1.9.2/1.9.3 releases.
The website for the Expert book has some errata and details some of the changes in the 2008 CTP release which were relatively minor.
However the CTP release for the 2010 beta (and the corresponding 2008 compatible release) 1.9.6.16 changes much more.
Since the MSDN documentation is largely non existent, especially in terms of changes and data is scattered around blogs I am finding it harder and harder to rely on the current books (especially the expert one) since the f# landscape has shifted too much underneath it.
This question seeks to provide a (hopefully) comprehensive list of those areas which have changed and short details/links to further reading on how to deal with this.
As the basis for this I have added some issue which impacted myself.
The previously linked blog post lists many of the changes in terse form and is a good place to start but it doesn't cover everything by any means.
Attempting to keep to a specific aspect per answer would be sensible since this will make reading it easier.
In specific question form:
What changes have occurred to f# from 1.9.6.3 to 1.9.6.16 that render previous examples (especially dead tree documentation not amenable to easy correction) incorrect or deprecated and what remedial actions are possible.
The signature of Array.sort changed; it used to be in-place, whereas now it returns a fresh array and Array.sortInPlace sorts in place. (That's been a minor problem-point for customers; most other library-renames issues deprecation warnings that steer you in the right new direction, but in this case the function still works, but has a new signature, which can make this difficult to diagnose at-a-glance.)
http://research.microsoft.com/en-us/um/cambridge/projects/fsharp/manual/FSharp.Core/Microsoft.FSharp.Collections.Array.html
A number of books were written before FSharp.PowerPack.dll was split out of FSharp.Core.dll, so for many examples you need to ensure you've added a reference to the powerpack to gain access to certain library functions.
See also http://blogs.msdn.com/dsyme/archive/2008/08/29/detailed-release-notes-for-the-f-september-2008-ctp-release.aspx
Events
Expert F# Chapter 8 section: Events and Wiring
IEvent is entirely deprecated. Instead the various functions are defined on Event instead.
There is no longer any need to use create_HandlerEvent to make a completely compatible .Net event (one consumable from, say c# easily) instead you use the CLIEvent attribute.
If you make your event via DelegateEvent<T> then the resulting event is usable without requiring any reference to the FSharp.Core dll.
If you use Event<T> then you must include a reference to the FSharp core to be able to use it.
Naming convention changes
removal of most '_' within function names
removal of deprecated functions
Specific examples and their resolutions
List
reduce_left to reduce
Seq
sort_by to sortBy
group_by to groupBy
init_finite to init
Several functions including cons and generate_using removed
Array
scan1_left to scanReduce
reduce_left to reduce
Multiple types have moved from being part of the dedicated F# runtime (child namespace of Microsoft.FSharp, in assembly FSharp.Core):
bigint now an alias for System.Numerics.BigInteger.
Tuple is now System.Tuple
#light
#light is the default, as a result some examples online will not compile.
This has a relatively minor impact since most examples used #light anyway.
Syntax changes
with member ... and support removed. Use explicit member this.Foo for each
1.9.4 changes
the change to Symmetric Operator Overloading.
subtle changes to the handling of nulls with boxing and option types
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 14 years ago.
How do you explain your team mates the importance of commenting the code they write? I know some coders who write episodic comments while others leave a lot to be expected, what do you expect when you read comments?
There are some minimums:
All functions and classes should be commented
Try/Catch and exception handling is better to be commented
Constants hard coded in the code should be definitely
dummy objects and dummy classes, as well as TO-DO parts should be commented
When you get a code from a URL, the address should be cited in the comments for further consideration and copyright infringement problems
Also commits to the version control system should be well commented
Although comments should be kept to minimum, there is no need to comment a for loop definition when it is obvious,
I usually set ground rules for my programmers, they stick to it when it is well defined
The best comments are always concise, in a few words. It should say what's not obvious in the code. I see allot of people making obvious and therefore useless comments like:
if x==0 //if x equals 0 then...
oh really?! This is only "polluting" the code, because unless you're learning how to program, its pretty useless.
Even if the code is only yours, you should write comments as if you were about to share it with another programmer that is completely unaware of it. That way you make sure that you will always understand it, and in long term if somebody comes along and picks that code up, that person will be able to understand it and extend/use it.
I see comments as a boost of reusability. And I expect, like every other programmer, to fully understand a block of code with a single, simple and concise comment.
Write comments when you're writing code that's not intuitive. There's really no reason for commenting a method that just iterates an array, but when you fix a bug or have to hack something together to get around an issue, it's good to have a comment so you can quickly understand that code 6 months later (and not accidently undo it).
What do you mean by commenting code?
The actual code, or the function headers?
If you're actually talking about the code, it's a lost cause. You need to get them to write readable code and to break it into meaningful chunks. Commenting bad code doesn't make it into good code, it just leaves an inconsistent mess.
As for header documentation, you have to get them to capture the important things (e.g., surprises, directives) and compromise about trivial things (listing all parameters, repeating what the signature does). People hate documenting functions because most of the effort is spent writing trivial text that almost insults your intelligence (e.g., on getHandleToFile(), "this gets a handle to the file"). Since there are actually a lot less important details than one would expect, they'd be pleasantly surprised and would be more likely to invest the effort in those specific situations.
I think if you are writing code that others may someday have to follow, then it is prudent to leave good comments about what things are doing. If you are just writing something for yourself, the tendency is strong to leave minimal or none at all. That being said, I have had the "not so luxury" of having to go back to code I wrote 8 years ago and didn't comment adequately, in a language I don't use anymore (class ASP) and I can tell you, I wish I had left more comments!
I try to comment most of my public methods and classes, and in those comments you can read what the method does, what the meaning of the parameters is, and, if applicable, what the output will be.
I also sometimes put comments inside my methods, but, there I do not comment what I'm doing, but why I am doing it like that.
if the language you are writing in is not human readable, i suggest very granular method and procedure level comments.
if the language you are writing is human readable (C#, VB, etc..) i suggest that you use somewhat detailed comments at the method level and minimal comments at the procedure level.
Include comments for document generation on methods and classes.
Don't comment every line.
If you are doing something expected or that is not obvious from the code, explain why in comments.
The most important thing to do in commenting is to tell the truth. The number of times I've been investigating a bug only to find a section of code that is "less than obvious" along with a comment that says it's supposed to do the opposite to what it is doing. Who wins? You decide...
On a related note, any comment that is longer than the section it is documenting is normally too long.