I recently found two posts in StackOverflow about adding comments in programming. Posts : 1,2
After going through these posts i was eager to know a thing a comments.i.e :
1.Do adding comments in programming utilize system resource while compiling the code ?
Yes they do, but you probably have to add a lot of them to notice any difference.
Handling white space and comments is part of the "lexing" (lexical analysis) phase of compilation, so yes, they do consume resources in the process. As a previous commenter has said, it's so computationally cheap that you'd have to insert a lot of comments and white space (and maybe compile on a really slow computer) before you'd notice.
You may be interested in this document: Notes on How Parsers and Compilers Work.
The first rule of programming: write code that other people can easily read and modify. To achieve this:
Write short, clear, code blocks that are easy to read and thus easy to determine the "what".
Write unit tests to both convey the "why" and to provide a safety net when maintaining the code.
Everything else, including how long the code takes to compile, should be moot. So the answer to your question is "it doesn't matter".
Related
So I use XML Comments in my code to help explain Public Methods and Public Members, another developer has mentioned that not all of my methods have XML Comments. I use the rule, if public or protected, add XML comment, if private, don't.
Does this sound logical or is there some reason why you would XML Comment a private method?
There are no strong rules about comments, but I believe that it is good to comment public/internal/protected methods.
Sometimes I comment private methods when they are not very clear. Ideally code should be self-documented. For example if you have a method like
Item GetItemByTitle(string title)
then it is not required to write comments, because it's clear enough. But if a method could be unclear for other developers, please put your comments or rename/refactor the method event if it's private. Personally I prefer to read code, not comments :) If you have too many comments code becomes hard to read. My rule is to use comments only when it is required.
If on your project you have a convenience to document all methods including private methods, then follow this rule.
It makes sense to also comment private and protected members - possible reasons include:
another developer may need to use the code and a consistent commenting approach can prove helpful;
you may want to auto-generate a help/documentation file of the source code at some point; in this case, lack of Visual Studio XML comments can result in a lot of undocumented code.
I don't really see a good reason why you would limit XML comments to public members.
I subscribe to the guiding philosophy that a method should be simple enough that its signature describes exactly what it does. That being said, this is not always possible (especially when working with legacy code) so there are situations when a header comment is useful. Such as:
The methods use is not obvious (and cannot easily be refactored)
To generate api documentation
I don't think are really any hard and fast answers here, if it feels right to comment it then comment it
I always take it as a good practice to comment all my methods as equivalent to having to explain them to someone, as I would want to have them explained to me if I did not carry knowledge as to what is happening, and why.
We develop in a small team, and this really does help with team development. More so, I regularly use my OWN comments, to figure out what the heck my though process was 3 months ago when I look at a piece of code.
Absolutely worth it to spend some time in adding comments to the top of your methods / procedures that do some interesting stuff.
The question is a little unclear as to whether you are asking:
Should private code be commented in general? or
Assuming you do what to comment private code should you use XML or standard C# comments?
To comment or not
To answer the first question, needing to comment any code is a bit of a code smell. When you run into a situation that you run across code that is hard to read an needs explaining, your first attempt to solve that should be to change (usually by renaming things) so that the code is more readable. Using comments to explain an unclear method name should be a last resort.
There are some exceptions. Public methods of DLLs shared outside the solution should always be commented.
I recommend reading Robert C. (Uncle Bob) Martin's "Clean Code" book for more details on this.
XML or C# comments
In general, yes use XML comments for methods as opposed to C# comments. The XML comments show up in intellisense. Also, the XML comments are bound to the method and if you use refactoring tools to move methods the XML comments will be brought along with the method, whereas C# comments can easily be separated from the method.
One reason not to use XML comments is if you will be publicly distributing your DLL and the XML comment file. The XML file will contain comments for all your internal and private methods. So just make sure that you're OK with your customers potentially reading any of those comments on private methods.
Greetings each and all!
I'm currently looking into procedural generation of a road network and stumbled upon the L-system algorithm. From what I understand from various scientific papers on the subject, and further papers on the papers on the subject, the algorithm is changed to use "global goals and local constraints", in which the taken path is modified to fit input values such as terrain and population density. Now that part I understand, or atleast the overall concept, but how am I supposed to modify the algorithm?
Right now I have a string which is modified over timesteps according to a set of rules. I then analyze the string and move and turn as I go through the chars, render the result and get beautiful patterns on screen.
Now, to create a network of major roads, should I still use a base axiom with a ruleset and then apply the constraints? And if so, what could a set of good startvalues and rules be?
Or should I rather replace the basic ruleset with the constraints and global goals? And if so, what remains of the original L-system algorithm?
Any help is greatly appreciated, and for the record I'm doing this in C# and XNA, allthough I reccon this is more on a theoretical plane.
Thanks for your time,
Karl
So, I've been googling, reading and understanding more the last week and I've found a solution to the problem which I thought I might share.
I found this brilliant blog post which basically straightened everything out for me:
http://www.newton64.ca/blog/?p=747#7472
That post is based upon another blog post founded here:
http://mollyrocket.com/forums/viewtopic.php?t=730&sid=a9a2628b059a727cbde67309757ed178
Now, as far as the L-system goes, I'm not quite sure whether this approach really is an L-system anymore. Sure, there are similarities regarding the iterative process of building the network. In L-systems the string grows over iterations and branches are created using "[" or "]" (atleast in the cases I've seen), and in the approach I'm taking now a while-loop and a priority queue does pretty much the same thing.
I also would like to point out that I did not fully understand the papers "describing" how to use an L-system for generating a road network, so my reasoning might be a bit off here. But algorithm naming and boundries aside, I found a solution that works for me, which is good for now.
Happy coding!
Karl
I'm the author of the above blog post -- glad you found it useful! I never did get around to finishing Spare Parts -- and if nothing else, I'd have to change the name -- but you've got me thinking about it again.
Certainly, the algorithm I described probably isn't much of an L-system anymore; importantly, though, I think it's pretty much functionally equivalent. I'm a positivist when it comes to programming, so if it works, compile it!
EDIT: I've since taken down my old website, but I've recreated the post here. Hope it's still helpful!
I've been using reflector to decompile a couple simple c# apps but I notice that though code is being decompiled, I still can't see things as they were written on VS. I think this is the way it is as the compiler replaces human instructions by machine code. However I thought I would give it a try and ask it on here. Maybe there is a decompiler that can decompile and show the coding almost identically to the original code.
That is impossible, since there are lots of ways to get the same IL from different code. For example, there is no way to know if an extension method was called fluent-style vs explicit on the declaring type. There is no way to know if LINQ vs regular code was used. All manner of implicit operations may or may not be there. Removed code may or may not have been there. Many primitives (including enums) up-to-and-including 4 bytes are indistinguishable once they are IL.
If you want the actual code, legally obtain the original code.
Existing .Net decompilers generally decompile to the best of their ability.
You appear to be asking for variable names and line formatting, which for obvious reasons are not compiled to IL.
There are several. I currently use JustDecompile found here http://www.telerik.com/products/decompiler.aspx?utm_source=twitter&utm_medium=sm&utm_campaign=ad
[Edit]
An alternative is .NET Reflector found here: http://www.reflector.net/
I believe there is a free version of it, but didn't take time to look.
Basically, no. There are often many ways to arrive at the same IL code, and there's no way at all for a decompiler to know which was used.
No, nor should there ever be. Things like comments and unreachable code would just add bloat with absolutely zero benefit. The very best you can ever do is approximate the compiled code.
Git is smart and will "follow" changes in history to make merging easier and auto merge more for me. Conflicts are delineated by the lines that have not changed around the change. With K&R you get no ambiguous lines that have only "{" in them like you would in B&D. How would I test the limit of the context sensitivity that Git has in terms of the lines that surround a change?
I want to avoid resolving conflicts that I may not need to. But I need some way to test how many potential conflicts I will save by switching to K&R and the additional context it brings.
So far, Git is too smart to get fooled by trivial examples.
Any help is appreciated. Thanks in advance.
So this is the closest thing I have found so far as evidence to this.
http://git.661346.n2.nabble.com/Bram-Cohen-speaks-up-about-patience-diff-td2277041.html
The e-mail is discussing the purpose of the "patience" algorithm in Git. In it Bram explains how superfluous matching lines can create nasty conflicts that can be tough to resolve but only in the case of fairly complex merges involving large patches. In other words simple contrived examples will fail to show this behavior.
While he does also mention things like End affecting the results it makes some sense to infer that placing an opening brace on it's own line increases the number of superfluous matching lines possibly resulting in a greater probability of these conflicts.
I'd say this isn't iron-clad, but it does lend some credence to this theory.
So 'unique lines' is a simple cross-language proxy for 'unimportant
lines'.
That quote stands out to me in this discussion, since we are basically matching on what we feel are important lines that are supposed to give us context, however a brace by itself is not important and provides no context.
Pick standard that is easier for you/your team to read over anything else. No matter how your source control system behaves today it will behave better tomorrow, but your code will stay the way you've checked it in for long time.
We have several large projects (over 200+ code files), which contain a massive mixture of both K&R AND B&D. I can safely say that after almost 2 years on Git, a development staff that is refactoring-crazy, and a rebasing behavior of "several time a day", that I have never had a conflict due to coding standards things. So pick whichever, or both, or neither. It won't matter.
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 6 years ago.
Improve this question
I currently support an application at work that was originally written by a team of four but has now reduced to just me. We recently got a contractor in to look at some performance issues while I'm occupied with other things.
While the contractor has appeared to do a good job with the performance, they have also gone through large amounts of the code replacing the pre-existing style with their personal preference.
Unfortunately we don't have a coding standards doc, just a general rule to adhere to c# general rules.
As an example of what they've done, it includes:
removing nearly all the uses of the 'var' keyword
Anywhere with an if statement and a single line, they've added curly braces
Removing most of the lambdas and replacing it with more verbose code
Changing method signatures so every parameter is on a separate line rather than one line
We also operate a TDD policy but the test coverage, especially on the performance specific parts, is very low leaving very little documentation on what they've changed and making it even harder as their checkin comments aren't particularly helpful and the actual functional changes are lost amongst the swathe of 'tweaks'.
How do I talk to the contractor about this? Obviously there's not much impetus on them to change it given they have no responsibility to support the project and they don't seem particularly receptive to change.
Or should I just put up with it for the short duration of the contract then change everything back to the code formatting we used before?
Made community-wiki 'cos there's probably not one right answer here.
Anywhere with an if statement and a single line, they've added curly braces
This one and the only one may be beneficial.
removing nearly all the uses of the 'var' keyword
Removing most of the lambdas and replacing it with more verbose code
Changing method signatures so every parameter is on a separate line rather than one line
These ones make little sense to change.
Tell him he's not authorized to restyle code. You won't be paying for the time wasted for these activities and they'll have to use their own time to put things back. That should provide a refreshment.
These things should be discussed in advance. You should state clearly what activities are allowed and what not. Not a long ago there was another similar question here about a contractor who would put his initials all over the code including database entities. It was some perverse kind of self-promotion for which there is no place in someone else's code.
P.S. There may also be a possibility that by doing all these things your contractor is artificially creating extra workload to bill you more hours.
I'm a contractor (sometimes) and if I did this I would expect to be shown the door with great speed and no payment. Seriously, this person is hired by you and should be doing exactly what he is told to do, no more and no less. And don't worry about being "nice" - contractors don't expect that from permies.
How do I talk to the contractor about this?
Politely: explain why you want to minimize changes to the source code.
ALternatively, have a code inspection of the changes before check-in: and don't allow check-in of changes that you don't understand/don't want/haven't been tested.
Implement FxCop - this should be your first line of defense. Also if you use source control (if you don't then implement one ASAP), make sure to use dev labelling (only build on file that have been labelled for the build), and don't give him rights to move labels on the files. This way you can scrutinize his changes, and refuse to dev label his code until it meets your standards. Whatever he codes won't make it into QA until you move the dev label to the revision in question, so he's pretty much at your mercy there. Note that some shops don't use a single label for their sandbox builds, they like to apply new labels even to the sandbox, so you may be inclined to do that as well.
The problem has happened now, and as the other said it's an unjustifiable waste of your money and it's outright impolite (as correct as the curly braces thing may be).
Certainly to help prevent future problems, and maybe helpful to resolve this, I'd advise you set up a stylecop implementation - at the very least they can't fail to be unaware of when they are breaking your rules.
I think we all know the temptation of seeing coded we think is "not the way I'd do it". But we resist it.
I would have a chat about it with your boss first to get their take on it. But the first thing that springs to mind is that unless you specifically asked the contractor to do the work, he was not doing what he was hired to do, regardless of any benefit he thinks he may have been adding. So there needs to be a discussion about that.
The next thing that sprung to mind is that regardless of how good they may be or well intentioned, people who make bulk changes without discussing it with the owners of the code are bad news. They will piss people off, or worse introduce bugs and unforeseen behavior that you will have to clean up. He needs to be set straight that doing this sort of thing without permission on other peoples code is not acceptable.
When I see things I don't like in others code which are serious enough to warrant attention, I check with the owners of the code first. Even if there are obvious bugs, it
s their code and their decision about cleaning it up, not mine.
As others have said, these changes are simply for coding style. If he is there to improve performance, he is wasting time with these changes. If he can't cite how these changes will improve performance, then his OCD is just running up the bill.
I would say, "I appreciate your changes to the coding style, but lets focus on non-style changes to areas of the code that are causing the slowdown."
If a contractor did wholesale reformatting of code without authorization, I'd give him one and only one change to put things back the way they were -- and on his own time.
In addition to the valid points others make, consider the version-control nightmare this causes. Instead of the clean progression of a few lines added here, a few lines changed here, you now have this "rift" in your source control database, so that any comparisons between versions before and after this contractor's "improvements" will be meaningless.
Have the contractor back out all of his changes. Today. And on his own time.
This is quite common my experience, that people can't resist making 'improvements' and suddenly you find you're billed for stuff you didn't want. Sometimes I'm sure it's done deliberately to get more paying work, but mostly I think it's a developer getting side-tracked and unable to deal with leaving 'wrong' code.
It might require a bit of a battle, but you basically have to keep reiterating "don't change anything you're not asked to work on". Depending on his personality, you might just have to ask once nicely, or get someone higher to force him.
First, as others have said. You are paying the bill. He is not an employee. His job is to do what you ask him to do, and only what you ask him to do, otherwise you can show him the door. Always remember this. You are driving the boat, not him. You can try to not pay him, but that will be hard to do if you have a legal contract and there is nothing in it about leaving code as-is. But, you can simply let him go at any time.
Second, if you can't get him to stop and revert, and you can't get rid of him, you can tell him that if he plans to do style changes, then he should do all style changes in one check-in with absolutely NO code changes. This allows you to move forward from a base set of code that can be diffed to see code changes.
Third, make him explain the justification for the changes he's made. Removing var has no performance benefit.
Fourth, and this may suck a great deal, but youc an always use ReSharper to put the code back to your accepted style after the fact. It's more work, and you still have borked diffs, but oh well. The lambdas are harder, and that's the one you should really get on his case about.
Fifth, to drive home your point, force him to back out every change he's made and re-implement only the code changes, and not the style changes. That should open his eyes as to the mess he's created when he can't figure it out himself.
Finally, you may just have the bite the bullet and PAY him to revet back. Yes, it sucks, but since you made the mistake of not policing him, not specifying up front what you wanted, and what he's not allowed to do... You will pay the ultimate price. You can either pay him to do it, pay someone else to do it, pay you to do it, or live with it (and pay the price of the borked diffs). Any way you cut it, it will cost you money.
Well, smells like a solution wide code reformatting to me, that could be automated/enforced by settings in a tool like Resharper. I would think it very impolite and would ask him to refrain from pressing the "Reformat all code according to my personal taste" button.
To avoid the situation happening in the first place, introduce code review, particularly for any new developers joining who may not know your standards.
I'm a big fan of using git, feature branches and a service that supports pull requests (github or bitbucket). TFS isn't really up to the job, but thankfully Visual Studio supports git now. Doing code review before merging to master ensures it doesn't get forgotton. If you're paranoid you don't even need to give contractors write access to your primary repository.
Alternate point of view:
Your make two statements: "While the contractor has appeared to do a good job with the performance" and "they have also gone through large amounts of the code replacing the pre-existing style with their personal preference."
This raises many questions such as: Whenever you can "drop in" a contractor for a short period of time and gain performance enhancements. This indicates that there must have been very major flaws in the application in the first place. Anytime you need to bring in a contractor to "fix performance" this is a sign of very poorly written code or a very complex problem that requires high end expertise.
Next: When you complain that they have changed the code style even though you did not have any stated code style are you just making a pointless argument about your mojo being better than someone else's mojo. Maybe you should ask the person why they made changes which appear syntactical such that you have a complete picture.
I'm looking at the long list of one sided answers on this post and wondering what happened to the other side. Folks take the emotion out of it and look at it objectively. It's often amazing how many people will look past a beautiful algorithm solution to a complex problem just to notice that the variable naming convention has been altered from camel case to pascal case. I generally put this type of reaction down to justification of self worth by finding immaterial flaws.
Key question I have to ask is: Does the newly formatted code make the application any less readable. If you had budget constraints why did you not make it explicit that you wanted very specific fixes and nothing else. If you wanted to maintain a specific coding style then why not have that explicitly stated?