10 Commandments
-
Why even have a main body inside the for loop? Why not:
int i = 0; while (i < 100 && ReturnTrue(new MethodInvoker(delegate { DoSomething(i++); }))) ;
:rolleyes:
I used to code that way, I got tired of being the only one to be able to understand my code. In designing electronic circuits, I learned that if you want the technician to correctly build what you intend the circuits need to be drawn in their classic configurations ie: a voltage divider with the resistors one over the other, op-amps input on the left output on the right. It is the way they learned to use and understand them. The most complex code is build of simple structures. HoleyMoley
-
I agree with most of them, but one that really bugs me is:
for (int i=0; i<100; i++) { DoSomething(i); }I prefer:for (int i=0; i<100; i++) DoSomething(i);or:for (int i=0; i<100; i++)
{
DoSomething(i);
}With the last one, who knows what future statements may need to be added... Another one that bugs me is stating that 4 spaces should be used instead of Tab, sorry, Tab tab tab ;P
"The clue train passed his station without stopping." - John Simmons / outlaw programmer "Real programmers just throw a bunch of 1s and 0s at the computer to see what sticks" - Pete O'Hanlon "Not only do you continue to babble nonsense, you can't even correctly remember the nonsense you babbled just minutes ago." - Rob Graham
-
I have been asked to work on our Code Review Procedure. This sort of thing: Pascal casing used for type and method names Camel casing used for local variable names and method arguments ... A single file should only contribute types to a single namespace. Avoid having multiple namespaces in the same file. Avoid files with more than 500 lines (excluding machine-generated code). Avoid methods with more than 25 lines. ... Never hard-code a numeric value, always declare a constant instead. ... I have the feeling it is missing what really make maintenance go bad. Things like re use existing classes, don't duplicate code, separate logic, data access, and display. Can anyone point me to some documents with good recommendations of this type. The idea is to minimize defect and certainly not to alienate the programmers (including me).
I prefer to ignore all formatting arguments. I've given up on trying to enforce tab rules - every editor seems to handle them differently. Most languages have pretty-printers, and/or they're not horribly difficult to create. Here's what I have come up with for our standards (we're primarily C but some C#). Much of it is very subjective. The programmer should be allowed significant flexibility, with the most experienced, even-handed developer having the final say. Commenting: File header blocks Header blocks for functions and substantial data structures Adequate comment frequency and quantity Legible and helpful comments (perfect spelling/grammar not required) Accurate All commented-out code is worth retaining and explained Coding Style: Standard and consistent Braces around single-statement blocks (to eliminate macro-inserted logic bugs) Magic (hard-coded) numbers minimized Constant declarations used where appropriate Meaningful variable names (i is sometimes appropriate) Global and local symbols distinguished Architecture: Efficiency and maintainability tradeoff Encapsulation and cohesion Global and shared data minimized Entry and exit points minimized Non-standard or non-portable techniques avoided, or documented when used KISS Reasonable function length Reasonable nesting depth Exception conditions pre-empted or handled No redundant code No dead code All build warnings eliminated or addressed
-
I have been asked to work on our Code Review Procedure. This sort of thing: Pascal casing used for type and method names Camel casing used for local variable names and method arguments ... A single file should only contribute types to a single namespace. Avoid having multiple namespaces in the same file. Avoid files with more than 500 lines (excluding machine-generated code). Avoid methods with more than 25 lines. ... Never hard-code a numeric value, always declare a constant instead. ... I have the feeling it is missing what really make maintenance go bad. Things like re use existing classes, don't duplicate code, separate logic, data access, and display. Can anyone point me to some documents with good recommendations of this type. The idea is to minimize defect and certainly not to alienate the programmers (including me).
I had to do this at my last gig, only the shop had a very ingrown and long-established culture..."the design is in the code", "if the code is right, no one has to read it again", etc.. The approach I took which was at least moderately successful, was to first take the MS standards as the starting point -- they are pretty good and more importantly they set the tone for what is important and what is not. Stay away from the silly stuff like cunting comments or the number of spaces inside of comments and concentrate on what makes reliable, reusable, and readable. The second and more important aspect was to get the affected people involved early in a series of ongoing review/feedback opportunities so everyone felt like they had a chance to contribute. These don't have to be meetings - just post the in-progress standards somewhere and let people know they are available and you are taking comments. Those that are truly interested will participate, those that aren't ... they missed their chance. Also use 'guest authors' for specialty areas like .MSIs and SPROCs -- they know what is really important in their areas of specialty. We wound up with a set of standards and 'advisory' items which everyone pretty much adhered to, and that required a minimal amount of maintenance/updating on my part as MS went through its regular convulsions (er, new releases). Finally, make it clear that you have management support and that adherence to the final standards will be part of automated code reviews and individual performance reviews (you did get management buy-in at the beginning, right?). And of course, don't forget your body armor :suss:
“The trouble ain't that there is too many fools, but that the lightning ain't distributed right.” --Mark Twain
-
The problem is when different people edit the same files using varying setups - some using tabs, some using spaces, plus varying tab interpretations (4, 3, 8, etc ...). The end result is an indentation nightmare that looks as if a monkey has been dancing on your keyboard.
This looks like someone making his jobs easier, by making everyone else job harder. As I see it, as long as all the people on a project agree to a tab size there is no problem. And using spaces instead of tabs carry the problem that you will need to press the keyboard 4 to 8 times(depending on tab size) to indent and un-indent your code when with a tab you press only once. When in doubt, just put a comment line telling whoever wants to maintain your code your tab size.
-
You can just configure the IDE to replace tabs with spaces whenever you type them... Then again, it can do most of the indenting on its own too!
Yep, kind of my point. who needs to really worry about spaces when the IDE will fill them in for you. I'd rather be concerned about thought process while coding than to worry about how many spaces I've put in.
"The clue train passed his station without stopping." - John Simmons / outlaw programmer "Real programmers just throw a bunch of 1s and 0s at the computer to see what sticks" - Pete O'Hanlon "Not only do you continue to babble nonsense, you can't even correctly remember the nonsense you babbled just minutes ago." - Rob Graham
-
This looks like someone making his jobs easier, by making everyone else job harder. As I see it, as long as all the people on a project agree to a tab size there is no problem. And using spaces instead of tabs carry the problem that you will need to press the keyboard 4 to 8 times(depending on tab size) to indent and un-indent your code when with a tab you press only once. When in doubt, just put a comment line telling whoever wants to maintain your code your tab size.
rxantos wrote:
And using spaces instead of tabs carry the problem that you will need to press the keyboard 4 to 8 times
IDE's allow you to press TAB to insert spaces and SHIFT+TAB to unindent. It's just a matter of setting the correct option. You do not need to press the space key.
-
I have been asked to work on our Code Review Procedure. This sort of thing: Pascal casing used for type and method names Camel casing used for local variable names and method arguments ... A single file should only contribute types to a single namespace. Avoid having multiple namespaces in the same file. Avoid files with more than 500 lines (excluding machine-generated code). Avoid methods with more than 25 lines. ... Never hard-code a numeric value, always declare a constant instead. ... I have the feeling it is missing what really make maintenance go bad. Things like re use existing classes, don't duplicate code, separate logic, data access, and display. Can anyone point me to some documents with good recommendations of this type. The idea is to minimize defect and certainly not to alienate the programmers (including me).
I think the thing to emphasise in this kind of document is what the goal is, rather than trying to lay down detailed constraints on things like code layout. Ultimately they are down to personal preference, and trying to dictate them invariably leads to arguments. Instead try and set some overall principles. For example, here's how I began the coding standards for one of my previous employers: There are three guiding principles: • Code for documentation. The code is part of the design documentation. • Code for debugging. The code should be written so as to make debugging easy. • Code for modification. The code should be written so as to be readily modified. I also added this: Remember that a source file is for human consumption - it is part of the program's design documentation. At the very least it will be read by your colleagues and your boss, so: • The normal rules of spelling and grammar apply. • Keep it tidy. • Don’t try to be funny or rude. So when code reviewing the key question is “is this code sufficiently clear and understandable that another team member could modify it?” It is not “how many spaces have been used for indentation?” Can I also point you at ‘The Pragmatic Programmer’ by Andrew Hunt and David Thomas. It contains lots of useful advice on how software development should be done. They also have a web site here: http://www.pragprog.com/.
-
rxantos wrote:
And using spaces instead of tabs carry the problem that you will need to press the keyboard 4 to 8 times
IDE's allow you to press TAB to insert spaces and SHIFT+TAB to unindent. It's just a matter of setting the correct option. You do not need to press the space key.
-
I have been asked to work on our Code Review Procedure. This sort of thing: Pascal casing used for type and method names Camel casing used for local variable names and method arguments ... A single file should only contribute types to a single namespace. Avoid having multiple namespaces in the same file. Avoid files with more than 500 lines (excluding machine-generated code). Avoid methods with more than 25 lines. ... Never hard-code a numeric value, always declare a constant instead. ... I have the feeling it is missing what really make maintenance go bad. Things like re use existing classes, don't duplicate code, separate logic, data access, and display. Can anyone point me to some documents with good recommendations of this type. The idea is to minimize defect and certainly not to alienate the programmers (including me).
The best advice that I can offer is to decide on what factors are important to your (current) group of developers and what is not. Them try to standardize the things that you feel are important in the way that most (hopefully all) are willing to work with. There are a lot of good ideas for points to consider in the other discussion here and the links that have been provided. However, it is your group that has to live with the end result. You need to come up with something that everyone can buy into or it may never work. I have participated and even driven this process several times in the past. It can be very helpful if nobody takes it too seriously and everyone takes it seriously enough. Good luck!
-
There was once a time when I didn't know that either.