Coding Standards
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
Declaring all variables at the begining of the method is an old c++(i am not sure if it comes from c) standard closely connected with the variable block of sight. In c# i dont believe there is such thing. Today i was sooo close of declaring such variable
bool bResultBecauseMyBossDoesntLikeMoreThanOneReturnInTheMethods = false;
next time ask your boss if you need to put a comment to the line
i++;
Sometimes i wonder... why does they want us to comment everything like the next "programmer", who will manage this will be a monkey.
Microsoft ... the only place where VARIANT_TRUE != true
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
Coding Standards are the first step in an organization to removing code quality. My personal experience suggests that code reviews become about fiefdoms and pet "issues" of enforcing the standards instead of about the code, errors in the logic, mismatched to requirements, etc. Also, when you don't have standards it is a lot easier to read other peoples code. (You can intuitively know who wrote it; most people make the sames types of errors over and over as well) And, oddly enough, without standards but with code-review and team work the code base naturally coverages. I personally keep standards to something regarding actual quality. That said, I usually declare all variables at the top of a method. And always only have one return in a method, preferring if-statements over multiple returns. Bottom-line is as you experience things you will learn what works best for you.
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost "All users always want Excel" --Ennis Lynch
-
Coding Standards are the first step in an organization to removing code quality. My personal experience suggests that code reviews become about fiefdoms and pet "issues" of enforcing the standards instead of about the code, errors in the logic, mismatched to requirements, etc. Also, when you don't have standards it is a lot easier to read other peoples code. (You can intuitively know who wrote it; most people make the sames types of errors over and over as well) And, oddly enough, without standards but with code-review and team work the code base naturally coverages. I personally keep standards to something regarding actual quality. That said, I usually declare all variables at the top of a method. And always only have one return in a method, preferring if-statements over multiple returns. Bottom-line is as you experience things you will learn what works best for you.
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost "All users always want Excel" --Ennis Lynch
I'm quickly beginning to understand your thinking on the subject. I kind of felt that way about it already. And the more I think about it, the more it annoys me. However, I will say that our manager and the lead developer both offer assistance to clear up code, to write more efficient code, etc. So I suppose it could be much worse.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
-
Declaring all variables at the begining of the method is an old c++(i am not sure if it comes from c) standard closely connected with the variable block of sight. In c# i dont believe there is such thing. Today i was sooo close of declaring such variable
bool bResultBecauseMyBossDoesntLikeMoreThanOneReturnInTheMethods = false;
next time ask your boss if you need to put a comment to the line
i++;
Sometimes i wonder... why does they want us to comment everything like the next "programmer", who will manage this will be a monkey.
Microsoft ... the only place where VARIANT_TRUE != true
That makes sense. I'm pretty sure my manager is the guy who set the coding standards. And if I'm not mistaken, he has a background in C++ as well. He has quite an extensive list of areas in which he's knowledgeable, so that is probably where it comes from. And that's my point. You're supposed to write code with readability and maintainability in mind, right? Well, if that's the case, you shouldn't have to comment every single operation. The more complex operations, yes, I completely understand. Sometimes, even if you think a complex piece of code is readable, it may be better for the next person if you comment and summarize what's going on. But to comment on a "return" statement? Or an increment statement? That seems a bit ridiculous.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
-
Declaring all variables at the begining of the method is an old c++(i am not sure if it comes from c) standard closely connected with the variable block of sight. In c# i dont believe there is such thing. Today i was sooo close of declaring such variable
bool bResultBecauseMyBossDoesntLikeMoreThanOneReturnInTheMethods = false;
next time ask your boss if you need to put a comment to the line
i++;
Sometimes i wonder... why does they want us to comment everything like the next "programmer", who will manage this will be a monkey.
Microsoft ... the only place where VARIANT_TRUE != true
Argonia wrote:
(i am not sure if it comes from c)
It does. But I prefer leaving it away in C# and C++ code, since I don't feel like it'd give me any benefits in these languages.
Clean-up crew needed, grammar spill... - Nagy Vilmos
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
Do this next time:
/// <summary>
/// This is an addition method.
/// </summary>
private int Add(int a, int b)
{
//Any monkey can understand what the next line does,
//but since my manager does not understand, I am writing this comment
return a + b; // Add the two numbers and return the result
} -
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
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)
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
Matt U. wrote:
foreach (MyFileObj file in _myFileCollection)
Whoops - you didn't declare the
MyFile filevariable at the top of the method! ;PMatt U. wrote:
// Setup the class that will be returned 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:
// Setup the class that will be returned
someObj = new MyClass(); // Create a new instance of the MyClass class and store it in the someObj variable.
someObj.FileCount = count; // Store the value of the count variable in the FileCount property on the instance of the MyClass class stored in the someObj variable.There, isn't that better? :rolleyes:
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
// Setup the class that will be returned 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.
-
Argonia wrote:
(i am not sure if it comes from c)
It does. But I prefer leaving it away in C# and C++ code, since I don't feel like it'd give me any benefits in these languages.
Clean-up crew needed, grammar spill... - Nagy Vilmos
I use the declaration of the variables at the beginning of the method in my c++ coding, the code is read more easily and its more tidy, especially when you use complex stl structures and interators to them. One more reason is reuse of the variables which served their main purpose - for example a string used for XPath, or string used for middle string result or something like that. In my c# code i dont use that rule... i get yelled for doing it and putting prefixes on the variables showing their type X|
Microsoft ... the only place where VARIANT_TRUE != true
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
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.
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
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"); }
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
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
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
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. -
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
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run 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 // Add two numbers // Return obvious value but I might add the // 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.
-
Matt U. wrote:
foreach (MyFileObj file in _myFileCollection)
Whoops - you didn't declare the
MyFile filevariable at the top of the method! ;PMatt U. wrote:
// Setup the class that will be returned 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:
// Setup the class that will be returned
someObj = new MyClass(); // Create a new instance of the MyClass class and store it in the someObj variable.
someObj.FileCount = count; // Store the value of the count variable in the FileCount property on the instance of the MyClass class stored in the someObj variable.There, isn't that better? :rolleyes:
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
-
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
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.
-
Coding standards with my employer are strange based on everything I've ever known, everything I've ever read, everything I've ever been told. They are set in their ways and I don't think anything could change their mind on these internal standards. Here are a few: 1. Excessive commenting -- practically every operation in code has a preceding comment. No matter how descriptive the code is, and no matter how simple the operation may be, there is a comment such as the following:
/// /// This is an addition method.
///
private int Add(int a, int b)
{
// Add the two numbers and return the result
return a + b;
}private void Process(MyFileObj myFile)
{
// Make sure the parameter is not 'null'
if (myFile != null)
{
// Strip all the bad data from the object
myFile.StripBadData();// Add the file to the collection \_myFileCollection.Add(myFile); }}
2. Variable declaration -- this may not be so bad, so please correct me if I'm wrong. But I've never seen it done this way. According to their standards, all variables in a method must be initially declared at the top of the method, before anything else is done:
private MyClass MyMethod()
{
int count = 0;
MyClass someObj = null;// Iterate over the file collection foreach (MyFileObj file in \_myFileCollection) { // Make sure the file's name is not longer than 20 characters if(file.Name.Length <= 20) { // Copy the file to a new location file.CopyTo(@"C:\\SomePath\\" + file.Name); // Increment the counter count++; } } // A lot of other code // ... // Setup the class that will be returned someObj = new MyClass(); someObj.FileCount = count; // Return the class that has the data we need return someObj;}
The "MyClass someObj" isn't referenced until the very end of the method. Why should it be declared at the very top of the method? Maybe I'm missing something? I've never declared objects until the time I need them. These are just a few examples. There are some other things I don't really agree with, but I can't change any of them.
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run 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,whileandswitchcode 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:
/// /// Performs a file copy (a better comment is required here).
///
/// The result of the operation.
private MyClass MyMethod()
{
// For each file whose name is less than 21 chars...
int count = 0;
foreach (MyFileObj file in _myFileCollection) {
if (file.Name.Length <= 20) {
// Copy it to the new location
file.CopyTo(@"C:\SomePath\" + file.Name);
count++;
}
}// A lot of other code // ... // Return result MyClass someObj = new MyClass(); someObj.FileCount = count; return someObj;}
/ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
- Strip out all code within blocks (except block delimiters - i.e.
