|
Gerry Schmitz wrote: It's from COBOL.
You are missing the point....
The question is why C# coding standards might have been insisting that declarations be at the beginning of a method.
And it is much more likely that that is holdover from C, perhaps going through C++, than it is that it came from COBOL.
One then might wonder why C had it. And it is possible that it came from COBOL. But it also possible that it was just easier to write BCPL, and then B and C that way.
|
|
|
|
|
Do this next time:
private int Add(int a, int b)
{
return a + b;
}
|
|
|
|
|
Matt U. wrote: 2. Variable declaration I do declare all my variables in one block at the beginning, maybe it comes from COBOL - I'm still thinking in sections...
I'm not questioning your powers of observation; I'm merely remarking upon the paradox of asking a masked man who he is. (V)
|
|
|
|
|
Matt U. wrote: foreach (MyFileObj file in _myFileCollection)
Whoops - you didn't declare the MyFile file variable at the top of the method!
Matt U. wrote: someObj = new MyClass();
someObj.FileCount = count;
Now how is anyone supposed to understand that code with the single comment you've provided? Surely it should be:
someObj = new MyClass();
someObj.FileCount = count;
There, isn't that better?
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
Well, I don't think their standards apply outside of the work environment.
djj55: Nice but may have a permission problem
Pete O'Hanlon: He has my permission to run it.
|
|
|
|
|
Richard Deeming wrote: Whoops - you didn't declare the MyFile file variable at the top of the method!
Tsk. Tsk. In that case it's obvious then that foreach isn't allowed.
IEnumerator<MyFileObj> enumerator;
MyFileObj file;
using (enumerator = _myFileCollection.GetEnumerator())
{
while (enumerator.MoveNext())
{
file = enumerator.Current;
}
}
He who asks a question is a fool for five minutes. He who does not ask a question remains a fool forever. [Chinese Proverb]
Jonathan C Dickinson (C# Software Engineer)
|
|
|
|
|
Well, I'm going to have to dock you points for not commenting every line of that code. Without the comments, how is anyone supposed to understand it?
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
someObj = new MyClass();
someObj.FileCount = count;
You missed an opportunity for a comment there. I'm sorry but I'd have to ding you on a code review for that.
I have very few coding standards in place - my biggest ones are "be consistent" and "don't let your methods get too big". I don't get bothered about brace style (life is far too short to worry about how someone formats brackets). As long as the team can come to a consensus about how they write their code then I'm only really concerned with the logic. I've seen far too many faddy standards come and go to want to jump onto a particular standard now.
|
|
|
|
|
The comments are a bit much. I am not one of these "the code itself should be the comments" people, but if I find I need to do something out of the ordinary to make the code work, I will write an extensive comment along with the code. I KNOW I won't remember why I did that weird thing one month, much less six months, from now.
I will also comment some trivial changes if they come from a client edict that is the opposite of what they requested just a few weeks ago. That way when they ask for it to be changed back in a few months and complain that WE broke the code I can point to the date and say we changed it per your instructions.
I like having the variables all at the top of a function, but then I am old (pre-DOS 5 and the MS C 5.1 compiler). I don't like having to hunt for a variable declaration. Pascal also likes to have the variables defined before the code too. Shoot, COBOL has it's own section for the things.
|
|
|
|
|
My Team and me defined a Standard way of coding for our stuff, pretty lot of Basic rules in there.
Comments -> As much as needed as less as possible.
Pretty dmn good because a XML commentblock can explain the whole method and can be used in extracting a documentation out of your code.
variable declaration -> Classinternal starting with _ and lower letter / incoming externals starting with capital letter
Declaring the variables at the top of the method lets you make it a Region block if there are a lot so you can collapse that Region and don't get bothered by all the declarations
and yeah what i do and love a lot -> regioning #Region "dumbShit" //Code// #endregion
that gives me the possibility to comment the Region and tell everyone what to find in here, thats a plus for getting faster through the code and to the desired line (imo)
just some tips from out Styleguide
if(this.signature != "")
{
MessageBox.Show("This is my signature: " + Environment.NewLine + signature);
}
else
{
MessageBox.Show("404-Signature not found");
}
|
|
|
|
|
Ideally, every coding standard rule will have a rationale as to what benefit the rule brings.
Variables should be defined as close to their first use as possible in general. If they are re-used several times, I always redeclare them every time in a new {} block within the method to not accidentally re-use a value from the previous block.
Those comments are silly, you are exaggerating there, right? If not, the comments are such that you could possibly generate them with a tool (think of e.g. GhostDoc). It would even be a nice exercise to write such a tool!
Edit: code comment should mostly explain why something is being done, not what is being done, because the what is mostly self explanatory, or can be found out using debugging. The why is very hard to find out.
Wout
modified 13-Feb-14 10:40am.
|
|
|
|
|
I'm not joking in the least about the commenting standards. If it were allowed, I would paste an untouched, large block of code, or even share a file, just to put it out there.
djj55: Nice but may have a permission problem
Pete O'Hanlon: He has my permission to run it.
|
|
|
|
|
I am the programming department of my company, and I still adhere to point 2 almost religiously. It goes with the idea of self-documenting code: if I come to a piece I'd written some time earlier and need to remember the type and initialized value for PersonId , I know where to look. I can look at the top of the code block much faster than I can pull up and use a search tool.
As for point 1, I find that commenting "obvious" code is useful: what may be obvious today, when writing it, will not be so obvious when I have to revise the code four years later. My personal standard, though, is to make comments meaningful.
|
|
|
|
|
Gregory.Gadow wrote: I'd written some time earlier and need to remember the type and initialized value for PersonId , I know where to look. I can look at the top of the code block much faster than I can pull up and use a search tool.
Ctrl-click.
Wout
|
|
|
|
|
The problem with comments is that they are often not changed in sync with code updates. Another one is that meaningful comment today is often meaningless tomorrow. I am trying my best creating meaningful comments and this is an art and continuous learning.
Similarly I like important declarations at the top but I declare "utility" variables at the point of use.
|
|
|
|
|
Member 10088171 wrote: The problem with comments is that they are often not changed in sync with code updates. Another one is that meaningful comment today is often meaningless tomorrow. I am trying my best creating meaningful comments and this is an art and continuous learning
The problem with that entire statement however is it means that either code reviews are not occurring at all or that they are not being taken seriously.
If code reviews are done correctly then an incorrect comment should not show up.
|
|
|
|
|
There are no good uniform standards for commenting code (no intelliSense either) and despite best efforts issues with code comments are missed even by best reviewers. One of the more practical approach is using asserts and exceptions instead of comments. When meaningful comments are necessary I also add time stamp showing comment/code updates.
modified 13-Feb-14 15:46pm.
|
|
|
|
|
Member 10088171 wrote: and despite best efforts issues with code comments are missed even by best reviewers.
So are code bugs.
But reviews are on-going and the next go around is another chance to correct it.
|
|
|
|
|
The comments I add are generally for myself, especially if it's a method, control or a class I've never used before I find it useful to help me understand the implementation, especially if I know I will be using it again.
I don't add the obvious <c style="color:green;">// Add two numbers // Return obvious value but I might add the <c style="color:green;">// Add X and Y here or the later result will have a phase offset type comments.
I should add that I don’t recall the last time when someone stopped by or emailed with a request for an explanation as to how my code works or how to use it. (They may question the methods but not madness. )
It was broke, so I fixed it.
|
|
|
|
|
I find both these standards odd.
I've been using RCG (Ravi's Commenting Guidelines™) for 20 years and they have served me and my teammates well. The guidelines are simple:- Strip out all code within blocks (except block delimiters - i.e.
if , do , for , while and switch code boundaries). - The remaining code and comments should clearly represent the method's psuedocode. If it doesn't, you need to add comments.
The coding standard about declaring all local variables at the start of a method is complete nonsense, IMHO. To maximize readability, local variables should be declared on first use within the block to which they're scoped.
This would cause me to rewrite your example method thusly:
private MyClass MyMethod()
{
int count = 0;
foreach (MyFileObj file in _myFileCollection) {
if (file.Name.Length <= 20) {
file.CopyTo(@"C:\SomePath\" + file.Name);
count++;
}
}
MyClass someObj = new MyClass();
someObj.FileCount = count;
return someObj;
} /ravi
|
|
|
|
|
That's an interesting concept, and I may try and adapt that style of commenting. It's simple to understand and I believe it may work nicely. Even if they don't want to change it, I may adapt it for my personal coding standards. Thanks for the input, Ravi.
djj55: Nice but may have a permission problem
Pete O'Hanlon: He has my permission to run it.
|
|
|
|
|
When Code Complete was first published there was actually a chapter dedicated to this. The idea was that you would design your code with comments. It would go something along these lines...
step 1 was to write comments of how the code would work.
You could in theory then have a review meeting of just those comments. This in turn causes you to get a better understanding of what you are trying achieve.
step 2 was to add the code
-(int)add: (int)a b:(int)b
{
return a+b;
}
More importantly is that if you did step 1 properly then in theory someone else could do step 2 just by implementing your comments.
we did something similar at my first programming job out of college (20++ years ago) and it helped in slowing things down to get you thinking before writing. I don't follow it to the same detail today but I do find at times when I am working on something a bit complex to follow similar steps.
think of it like a mental dump of what you are thinking at the time you write the code. we have all asked the question when reading someone else's code.
What were they thinking when they wrote this piece of code?
I would take the time to learn more of how and where these standards started. there is generally a wisdom or history behind things like this and knowing that can help more than the actual standard itself.
you want something inspirational??
|
|
|
|
|
Very informative. I appreciate it. As previously stated, my manager has extensive experience with multiple languages. And I'm almost certain it came from quite a long while ago. Also, they have a lot of contractors (myself included) come through here. So I'm thinking the extensive commenting style may be in place to more or less protect future contractors and such from becoming easily confused. Who knows, I could be wrong.
djj55: Nice but may have a permission problem
Pete O'Hanlon: He has my permission to run it.
|
|
|
|
|
Matt U. wrote: These are just a few examples.
The examples you gave are excessive.
The declaration of variables at the top is actually a hold over from C programming.
|
|
|
|
|
But C# is not C. Is it necessary? I've learned throughout the life of this thread that it doesn't matter. It isn't necessarily good or bad. But does it benefit in any manner when coding in C#?
djj55: Nice but may have a permission problem
Pete O'Hanlon: He has my permission to run it.
|
|
|
|