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.
With respect to your first point, this is not good. I can tell you what the code is doing by reading it. Why is it doing that is the question the documentation should answer. The hardest part about good documentation is what I've called the "philosophical documentation." In other words, describe what you think the code is doing, and why you took this approach. Try to let a future developer (yourself included) get into your mindset when building this code. About the variable declaration, it depends. If it is truly just declaring method-scope variables, that's probably not so bad. If, however, the variables you declare require some potentially costly construction, then it's smarter to delay that until necessary. Your method might exit before hitting that constructor in some code path and save that cost, for example. I agree there is something to be said for the idea of 'closeness'. I feel like it makes the developer continually think about scope, but it's probably not such a huge deal.
-
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.
Defining the variables at the beginning of the code dates from the time of VB6. But I believe that currently the most common approach is to define the variable as close as possible to where it is being used.
-
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.
There are always multiple views on this kind of thing. Here's my 2 cents worth. Excessive commenting is a plague in my view. They interrupt the natural flow of what might otherwise be beautiful code. As a rule, I will take a functional block of code and block comment it in as much detail as I think is useful. The comment will usually be less about what it is doing than why and what for and any notes about anything strange/non intuitive that it is doing. But I'm really against small obvious comments with each and every line of code. As for the variable thing, in previous C standards, top of the block declarations were the only option. In newer ANSI, I believe this has been relaxed although here we don't tend to use it. At least in C++ you have the option of late declaration. For me, as an Eclipse user, pressing F3 to get to the declaration is second nature now and most decent development environments have such a facility. If you can't remember what the type is, a mouse hover will soon reveal that. Not so convenient for vi/emacs uses of course :D I would note that putting the declaration of a variable at the point at which it is initialised/first used reduces the possibility of accidental use when uninitialised. It also guards against the abomination of using a single general-purpose variable (e.g. i) for everything in the function. It might be slightly more efficient (although most optimisers would be converting these general purpose items into registers anyway) it is always tempting the accidental use of whatever was left in there from the previous use. I prefer not to do this. For a loop variable, declare it in loop scope, don't reuse the same variable all the time: for (uint32_t loop = 0; loop < max; loop++) {} etc In a block, declare it in block scope. As I said, a lot of these general purpose items will be registers anyway.
-
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.
Wow, some of the comments here against coding standards surprised me. I am a huge fan of coding standards, and code reviews. Especially when everyone works on the software. But I started with professional Basic Plus (on a PDP/11), which required no indentation, so people did not do it. LOL. A 16 way If then statement without ANY indentation. Worse, one of the programmers actually removed MY indentation. He said if you can't read the code, you are not a real programmer. We immediately adopted coding standards, and reviews. But pragmatically. Comments are OPTIONAL and NEVER increase the accuracy of code. But, in a review, ANY reviewer can request a comment clarifying a complex block of code. Or forcing a comment on a variable declaration whose usage must be understood. Over the next few months, we noticed the rates of defects in the code were dropping. We also found we were all getting better at predicting problems just by reading the code. So, I am all for coding standards and code reviews. But let me add, that ONLY to the degree that the rules make sense. One of the reasons to use a standard is that it is EASIER to teach a person to read structured code of ONE STYLE than to have to constantly switch styles. Most editors do the heavy lifting of formatting these days. My only issue with the coding style you have described is that it requires USELESS comments. Declaring variables at the top is required in other languages (Pascal/Delphi, COBOL). In C, I always liked blocked local variables. So, while i understand your frustration, have you read "Code Complete" or "Writing Solid Code". One way to attack the problem, is to get your boss to read some of the modern books (you should read them first). On my teams, ALL developers are REQUIRED to read a batch of 6 books on their own time. This helps us all speak the same language and communicate better. Just a thought.
-
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.
And I bet they completely ignore XML commenting and don't require it. (This does look like C#) Declaring the variables at the top does sound reminiscent of C/C++. One thing that drives me nuts is using #regions in C# to create a section for all of your fields, then another for delegates, then properties, then functions.... Sounds good until you have a data-object where each bit of data might have a field, an exposing property, and maybe an event or two to let people know when it's added/deleted/changed... and then someone wants to change or delete a property of the object and you have to go thru each region to find the methods and fields regarding that property.
-
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.
Matt U. wrote:
But C# is not C. Is it necessary?
Of course not. I was merely providing a historical source for why someone would do that. If you feel feisty you might ask if that is such a good idea why neither C#, Java nor C++ language creators didn't require it.
Matt U. wrote:
But does it benefit in any manner when coding in C#?
It might make someone more comfortable. Or it might might have made someone more comfortable 10 years ago but that guy has retired now (or gotten a different job.)
-
And I bet they completely ignore XML commenting and don't require it. (This does look like C#) Declaring the variables at the top does sound reminiscent of C/C++. One thing that drives me nuts is using #regions in C# to create a section for all of your fields, then another for delegates, then properties, then functions.... Sounds good until you have a data-object where each bit of data might have a field, an exposing property, and maybe an event or two to let people know when it's added/deleted/changed... and then someone wants to change or delete a property of the object and you have to go thru each region to find the methods and fields regarding that property.
They actually do require the #region separation. It's like this:
#region Variables
...
#endregion Variables#region Fields
...
#endregion Fields#region Properties
...
#endregion Properties#region Constructors
...
#endregion Constructors#region Methods
#region Private
...
#endregion Private#region Protected
...
#endregion Protected#region Public
...
#endregion Public#endregion Methods
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
-
Matt U. wrote:
But C# is not C. Is it necessary?
Of course not. I was merely providing a historical source for why someone would do that. If you feel feisty you might ask if that is such a good idea why neither C#, Java nor C++ language creators didn't require it.
Matt U. wrote:
But does it benefit in any manner when coding in C#?
It might make someone more comfortable. Or it might might have made someone more comfortable 10 years ago but that guy has retired now (or gotten a different job.)
I understand your point and I appreciate the insight. I'm just dealing with it, I have no control over it. It was simply against just about everything I've ever read/been told. But you live and you learn, right? :)
djj55: Nice but may have a permission problem Pete O'Hanlon: He has my permission to run it.
-
jschell wrote:
It is from C.
It's in Pascal, which AFAIK predates C. Which isn't to say that both didn't pick it up from some other language.
John Nurick wrote:
It's in Pascal, which AFAIK predates C. Which isn't to say that both didn't pick it up from some other language.
I seriously doubt that. First at least Wiki reports that development and C and Pascal both initially started in 1969. And certainly seems possible that Pascal wasn't terribly successful early on. Whereas C was actually being used in 1972. And C was proceeded by B and that came from BCPL. Of course C++ was derived from C. And in terms of where variable declarations occurred, C++ and Java would have had more influence on C# than C. Pascal wasn't in the picture. One might suppose that a Pascal programmer went directly to C# but it is more likely that either Java or C++ was the precursor.
-
jschell wrote:
It is from C.
It's in Pascal, which AFAIK predates C. Which isn't to say that both didn't pick it up from some other language.
-
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.
-
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
Wow, so much to hate here. First, code standards make it easier to read the code (if they make sense). You don't need a lack of standard to tell who wrote it. Besides your source control can tell you who wrote the code. Second, keeping variable declarations at the top and avoiding multiple exits of a method make code harder to read. And the whole if thing? Code quality is (generally) inverse to the number of if statements a coder uses. But I would find a new place to work as quickly as possible. The code standards show that this organization has not embraced the C# way of doing 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.
Probably, your manager's main metric is lines of code (with the comments). The more lines, the more productive he (and you all) look. If this is the case, then your manager needs a serious education in modern software design(including coding practices). If you really want to inspire your manager, write a full length paragraph for each line of code. (Pretend that you are writing software for the department of defense. They just love documentation, even if they don't understand what it does.)
-
It's from COBOL. You had a DATA DIVISION (variables) and a PROCEDURE DIVISION (executable code) ...and a few other divisions. The PROCEDURE DIVISION followed the DATA DIVISION and one could not mix elements of one with the other.
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.