Code guidelines
-
Daniel Wilson wrote: Where you work do you have "code guidelines" that you must follow? Yes, but they are "guidelines" so we should follow them, but are not forced to if the situation means it would be better not to. In general that means they get followed pretty much most of the time. Daniel Wilson wrote: are they language specific Yes, although we try to keep things consistent between languages if possible. One of the biggest difficulties in this area is "cradle-to-grave-naming" where a variable has the same name in each of the scopes that the data appears in. Sometimes integrating with other systems means that isn't always possible. But if everything is in, say, a C# application then it is maintained. If you don't do that already then you'll find it is a fairly easy discipline to pick up on a new project and it makes everything so much easier.
"If a man empties his purse into his head, no man can take it away from him, for an investment in knowledge pays the best interest." -- Joseph E. O'Donnell Can't manage to P/Invoke that Win32 API in .NET? Why not do interop the wiki way!
Colin Angus Mackay wrote: Yes, although we try to keep things consistent between languages if possible. One of the biggest difficulties in this area is "cradle-to-grave-naming" where a variable has the same name in each of the scopes that the data appears in. Sometimes integrating with other systems means that isn't always possible. But if everything is in, say, a C# application then it is maintained. If you don't do that already then you'll find it is a fairly easy discipline to pick up on a new project and it makes everything so much easier Could you explain this a little more? If I am understanding you correctly this would be an example of adhering to what you are saying. A key is in a text file. Every where that a variable is referring to this key regardless of its scope would be named, for example, "subscriptionKey". Thanks, Daniel
-
We have none. Each person here is a cowboy coder. I try to follow the guidelines/tips listed in the book Writing Solid Code. The book is a little dated, but has some real good commonsense tips. ================================ Freiheit ist von Gott, Freiheiten vom Teufel.
That is how it works where I work also. Do you think this is common practice or the exception?
-
That is how it works where I work also. Do you think this is common practice or the exception?
-
Where I work we do not currently have any written guidelines, no code reviews or anything. We have ABAP, Java, VB, and me who develops mostly in C# but can program in all of them. I am in the process of trying to push written guidelines for the individual disciplines and definitely agree that following the guidelines of the framework are the way to go. Do you augment the design guidelines with additional constraints such as all curly brackets begin and end on their own line? Or, not really code convention but more so process, mandate that every new application has a defined component specification, requirements doc, etc? Thanks for the info.
Do you augment the design guidelines with additional constraints such as all curly brackets begin and end on their own line? We all leave Visual Studio.NET's formatting alone. Aside from syntax coloring that is. (I prefer dark blue for strings and numbers, while another coworker prefers a maroon-ish color or something.) So curly braces go on their own lines, etc. If I don't like the way a co-worker formats his code, I just go to the end of the file and retype the last curly bracket. ;) I work for a title company, in the software development division. We basically work as a separate division. If the title division wants a project done, they contact the department head, we basically do "contract" work for them. Which means that we draw up project specs, estimate hours, tell 'em how much it's gonna cost, and see if they approve the project. So yes, we always have requirements docs (complete with pretty Visio diagrams and mock-up UI images), we do unit testing and formal user testing, we have a Flash developer make a small tutorial for how to use the application. We write up end-user documentation and FAQs and then we train certain people within the operations divisions who then go out and train the others. That's pretty much it. It's a lot of work, but it makes managing the projects a whole lot easier. Hope that helps. :)
Quantum materiae materietur marmota monax si marmota monax materiam possit materiari?
-
Colin Angus Mackay wrote: Yes, although we try to keep things consistent between languages if possible. One of the biggest difficulties in this area is "cradle-to-grave-naming" where a variable has the same name in each of the scopes that the data appears in. Sometimes integrating with other systems means that isn't always possible. But if everything is in, say, a C# application then it is maintained. If you don't do that already then you'll find it is a fairly easy discipline to pick up on a new project and it makes everything so much easier Could you explain this a little more? If I am understanding you correctly this would be an example of adhering to what you are saying. A key is in a text file. Every where that a variable is referring to this key regardless of its scope would be named, for example, "subscriptionKey". Thanks, Daniel
Normally, coding guides say things like keep abbreviations the same, e.g. Number is consistently abbreviated to Num and never to No, or vice versa. This idea is just taking it a step further. Daniel Wilson wrote: If I am understanding you correctly this would be an example of adhering to what you are saying Yes, or derivatives of it. If the file is, say, a fixed width text file and subscriptionKey is an integer you might have some code like this:
string subscriptionKeyString = fileLine.Substring(5,10); int subscriptionKey = Convert.ToInt32(subscriptionKeyString);In this instance the word "String" is appended to the base name as it is in a type that the variable won't normally be associated with. You can also use "fileSubscriptionKey" if you prefer to denote where the value came from rather than its type - Hugarian notation is mostly out these days. But everywhere you can you would ensure that the variable is named the same. Then, if you are maintaining the code you can make good assumptions about what a variable actually contains - a little discipline in this area can really pay off over the long run. A second example of where you might find differences is if you have two variables containing a subscription key. For example:
public SubscriptionItems FindSubscriptionItems(int subscriptionKey)
{
foreach(int TestSubscriptionKey in this.keys)
{
// Do something to test if subscriptionKey matches the TestSubscriptionKey
// and perform appropriate actions.
}
}In this case the exposed version is given the base name, and any internal versions have prefixes or suffixes. The only problems I've encountered is where the coding guides for one system conflict with another and they are being integrated. I've worked on integrating a .NET application with a SAS system with SQL Server 2000 sitting in the middle. Three sets of guidelines have to be brought together. SAS has some interesting "features", for example it can't have a table or column name greater than 32 characters, many valid names in SQL Server are impossible in SAS and so on. What we actually ended up with (because the SAS developers weren't going near C# and vice versa) was that the SQL Server side adhered to the SAS naming guidelines, C# used the same names but Pascal/Camel cased as appropriate. The only difficult bit was in the Data Access Layer in C# where the two naming schemes met. But, there were consistent rules about how to convert
-
That is how it works where I work also. Do you think this is common practice or the exception?
-
Normally, coding guides say things like keep abbreviations the same, e.g. Number is consistently abbreviated to Num and never to No, or vice versa. This idea is just taking it a step further. Daniel Wilson wrote: If I am understanding you correctly this would be an example of adhering to what you are saying Yes, or derivatives of it. If the file is, say, a fixed width text file and subscriptionKey is an integer you might have some code like this:
string subscriptionKeyString = fileLine.Substring(5,10); int subscriptionKey = Convert.ToInt32(subscriptionKeyString);In this instance the word "String" is appended to the base name as it is in a type that the variable won't normally be associated with. You can also use "fileSubscriptionKey" if you prefer to denote where the value came from rather than its type - Hugarian notation is mostly out these days. But everywhere you can you would ensure that the variable is named the same. Then, if you are maintaining the code you can make good assumptions about what a variable actually contains - a little discipline in this area can really pay off over the long run. A second example of where you might find differences is if you have two variables containing a subscription key. For example:
public SubscriptionItems FindSubscriptionItems(int subscriptionKey)
{
foreach(int TestSubscriptionKey in this.keys)
{
// Do something to test if subscriptionKey matches the TestSubscriptionKey
// and perform appropriate actions.
}
}In this case the exposed version is given the base name, and any internal versions have prefixes or suffixes. The only problems I've encountered is where the coding guides for one system conflict with another and they are being integrated. I've worked on integrating a .NET application with a SAS system with SQL Server 2000 sitting in the middle. Three sets of guidelines have to be brought together. SAS has some interesting "features", for example it can't have a table or column name greater than 32 characters, many valid names in SQL Server are impossible in SAS and so on. What we actually ended up with (because the SAS developers weren't going near C# and vice versa) was that the SQL Server side adhered to the SAS naming guidelines, C# used the same names but Pascal/Camel cased as appropriate. The only difficult bit was in the Data Access Layer in C# where the two naming schemes met. But, there were consistent rules about how to convert
excellent explaination. Thanks. I definitely see value in promoting consistency through that sort of naming.
-
I really don't know because this is the first place I have worked since graduating college. I would assume not. ================================ Freiheit ist von Gott, Freiheiten vom Teufel.
waffleman wrote: I really don't know because this is the first place I have worked since graduating college. I would assume not. You know, when I first graduated and set up a software development company I was thinking that all the other companies had better coding standards and so on. This was around the time that Rapid Development and Code Complete were first published. We went through the books and pulled out everything that would make our lives better and implemented it slowly over a couple of years (so it wasn't too much of a culture shock). Anyway, eventually the company started to slide financially and some people had to leave, including some of the co-founders. They reported that the standards we put in place were far above what their new companies had. Since then they've spent time introducing these standards to their new companies.
"If a man empties his purse into his head, no man can take it away from him, for an investment in knowledge pays the best interest." -- Joseph E. O'Donnell Can't manage to P/Invoke that Win32 API in .NET? Why not do interop the wiki way!
-
That is how it works where I work also. Do you think this is common practice or the exception?
Code Complete and Writing Solid Code are both excellent books, even if they are dated they still contain excellent advice. Code Complete (I think) has been recently updated and revised and a second edition is now available. I think that if you are basing your current standards and practices on either of these books you are doing better than many.
"If a man empties his purse into his head, no man can take it away from him, for an investment in knowledge pays the best interest." -- Joseph E. O'Donnell Can't manage to P/Invoke that Win32 API in .NET? Why not do interop the wiki way!
-
Code Complete and Writing Solid Code are both excellent books, even if they are dated they still contain excellent advice. Code Complete (I think) has been recently updated and revised and a second edition is now available. I think that if you are basing your current standards and practices on either of these books you are doing better than many.
"If a man empties his purse into his head, no man can take it away from him, for an investment in knowledge pays the best interest." -- Joseph E. O'Donnell Can't manage to P/Invoke that Win32 API in .NET? Why not do interop the wiki way!
I agree both are excellent resources and despite my praise for both of these resources I am having difficulty convincing my coworkers of adopting standards above and beyond those imposed by the languages themselves. For instance, standardizing on a basic indentions structure, whether or not to use hungarian notation, and avoiding where appropriate indentifing the implementation in the method name (GetNextUser() as opposed to GetNextArrayElement() ). The common response is these are "best practices" not standards and it should be up to the individual developer to follow a style that is useful to them thus increasing their individual productivity... Please don't misinterpret this last statment. I know that standards should be guidelines but I am not certain that everyone sees the value of following these guidelines most of the time is beneficial. Thanks, Daniel