Journal greginnj's Journal: Development Standards
Programming Standards
(Score:5, Insightful)
by clockwise_music (594832) Alter Relationship on Wednesday November 16, @08:27PM (#14048944)
(http://www.metaltheater.com/ | Last Journal: Friday May 06, @01:41AM)
In no particular order:
1. Get a development database, a testing database and production database. Yes, you need all three.
2. Write a few docs explaining each system. Make these are detailed as you possibly can. (This will save you weeks in the long term)
3. Use software revision control. CVS, VSS, whatever, use one.
4. Use a bug tracker. BugZilla, Jira, CityDesk, whatever, use one.
5. Use whatever coding standards the language reckons you should. If java, use sun's standards. If microsoft, use their standards.
6. Write automated unit tests. I don't care if you're not an agile or XP developer, write unit tests. Check out Junit, or Nunit, or just write your own.
7. Setup some code so that you can check out ALL code from the source code repository and compile it by ONE COMMAND. Eg, "make" or "ant" or "maven" or whatever. This will take time but is worth it.
8. Have a naming standard for database tables. This will make your life SOOOO much easier.
9. Read thedailywtf.com and don't do anything that is posted there.
10. Write specs for your new developers. Please write specs for your new developers. Don't just say to them 'fix this up'.
11. Make sure code isn't hard-coded to a particular directory. Everyone does this. Fix it. (Might be part of step 7)
12. Create your own standard config files.
13. Have code reviewed by peers. Don't be a bastard but be nice when picking on people's code.
14. As mentioned, comment your code but use the language standard. Java - javadocs, Perl - perldocs, etc. These are cool, but don't get too carried away. Nothing can replace a good spec.
15. Ignore what most people say on Slashdot. (Except for me, of course).
That'll keep you busy for a couple of months! Doing thiswill make you well on the way to having a pretty high level of coding quality. Most companies don't do all of them. Good luck.
1.a Get a test application server and production application server. Yes, you need both. The development server would be the developers workstation.
6.a Formalize the testing process by people other than the original developers.
6.b Write test cases.
6.c Do regression testing. Especially for "transperant to the user" changes.
8.a Have a naming standard for table columns. This will make your life SOOOO much easier.
11.a Where you do need hardcoded directories, externalize the locations in configuration files.
--
- - - - - - - - - - -
I am a programmer. I am paid to produce syntax not grammar. Deal with it.
Great post. Some additions...
1. Use a code reviewer like FxCop for .NET stuff. You can build custom rules that your team decides on, and apply them to each program.
2. Automate as much as possible with things like Ant or NAnt. The less people do, the less room for errors or discrepancies from project to project.
3. Use something like Cruise Control .NET which will tie everything together, run coverage reports, automate builds, etc.
4. Make a Utility library so that they have a common place to get repetative processes. (e.g. we have one that validates whether a number and address is a valid store for our company; it is used in 75% of our programs, but only coded once.) You could incorporate some common error handling like log4net or log4j into the utility.
Here a just a few things that come to mind:
1. Version Control - find a VC system everyone can agree and use it religiously, whether for scripts, programs, or even web docs. I've use CVS mainly, with a little Perforce, and Subversion is good so I hear.
2. Coding Standards - depending on how many and what type of languages you have, you'll want to develop standards for how code will be laid out and documented that will make sense and also make it easy for somebody to move from one code base to another with as little trouble as possible. You can be as detailed as like, right down to conventions for naming subroutines and indentation, but don't get carried away or you'll stifle creativity.
3. Documentation - not just documenting code (which any programmer should be doing reflexively), but documenting system flows and procedures. It doesn't hurt to throw together text docs on your more important scripts/programs, outlining where they live, how they're run, etc.
4. The Brain Book - there's nothing I hate more than starting a new job and having to learn all those server names, IP addresses, what I'm supposed to have access to, where in the directory tree the stuff I works on live, what types of DBs we use and their versions, etc. So I developed the Brain Book, where I would write these things down as I learned them, to have a point of reference. It's a good idea to do this for all your major projects, so as new people come on, they can spend less time learning their way around and more time coding.
5. Code Review - everybody's coding style is different and sometimes they don't mesh well or there are divergent opinions on how a particular task should be coded out. Get your programmers together in a room and hash things out as a group. It will provide everyone with a say and may open up some people's eyes to new ways of doing things.
on this particular subject. i believe code complete 2 came out "reasonably recently". that said, were this my task, i'd say the following:
1) document things thoroughly using a tool like doxygen. there is no excuse for interfaces not to be thoroughly documented
2) adopt a standard naming convention. in java, this is easy -- just use the default. in other languages, you'll probably have to make your own up.
3) pick an indentation style. it really doesn't matter which since tools like indent can convert between them almost painlessly. all code that goes into the repository is run through indent to put it into a standard format
4) require that code compile cleanly with no warnings at the most anal retentive compiler settings before it can be checked in unless there are good reasons to ignore the compiler warnings
5) average devs are only able to commit to the "head" fork (or equivalent in your sccs). the code is not committed to the "real" fork until it passes whatever tests you have
6) incorporate tools like valgrind into your testing cycle --- they should come back largely clean. if they don't, things need to be fixed unless there's a really good reason not to.
7) people who check in code which breaks cvs or, upon a code review, are found to not sufficiently adhere to your guidelines owe their dev group donuts.
[ Reply to This ]
We don't need no coding standards!
(Score:5, Informative)
by MythoBeast (54294) Alter Relationship on Wednesday November 16, @08:28PM (#14048949)
(http://www.mythologicalbeast.org/ | Last Journal: Monday September 08, @01:27PM)
Ok, so the subject is misleading. As a C++ contractor with about 15 years of experience in a broad variety of shops, I've been exposed to quite a lot of different coding standards, from severely strict where they told me where and when I can use the spacebar, to the completely non-existent. Of all of them, I have found the GNU coding standards [gnu.org] to be the best balance between the flexible and the legible.
A few other details that I'd like to add. K&R braces were invented, not by K&R but by the guys who typeset their book. It is a severe roadbump to try and read code where the braces are at the end of an if statement instead of vertically alligned.
Try spinal alignment for variables. Most people align their variables like this:
int something;
void somethingelse;
longobjectname theThirdThing;
Those with more of a clue align them so that you can find the variable name easily in a mess of them:
This puts some major space in some cases between names and short type declarations. Try aligning them like this:
...........int..something;
..........void.*some thingElse;
longobjectname..theThirdThing;
The problem with this technique is that, if you ever post your code on Slashdot, you'll have to replace spaces with dots and spend fifteen minutes trying to get it to render correctly because SD doesn't support a simple PRE tag.
Other tidbits that have helped. camelNotation rules. Don't use hungarian notation, it doesn't work in a severely object oriented enviornment. Instead, preceed your variables with a single letter that tells you where it's declared. l for local, m for member (of a class or struct), g for global, that kind of thing. I've seen "my" used for member and "the" used for static very effectively, also, but stick to one.
Most of all, good luck. Remember that a lot of people's beliefs in this matter have no foundation except for what they've been doing for years. I have faith in my standards simply because I've seen what happens when you don't follow them, and that's mostly confusion.
Gnu coding standards:
http://www.gnu.org/prep/standards/
(Score:5, Insightful)
by clockwise_music (594832) Alter Relationship on Wednesday November 16, @08:27PM (#14048944)
(http://www.metaltheater.com/ | Last Journal: Friday May 06, @01:41AM)
In no particular order:
1. Get a development database, a testing database and production database. Yes, you need all three.
2. Write a few docs explaining each system. Make these are detailed as you possibly can. (This will save you weeks in the long term)
3. Use software revision control. CVS, VSS, whatever, use one.
4. Use a bug tracker. BugZilla, Jira, CityDesk, whatever, use one.
5. Use whatever coding standards the language reckons you should. If java, use sun's standards. If microsoft, use their standards.
6. Write automated unit tests. I don't care if you're not an agile or XP developer, write unit tests. Check out Junit, or Nunit, or just write your own.
7. Setup some code so that you can check out ALL code from the source code repository and compile it by ONE COMMAND. Eg, "make" or "ant" or "maven" or whatever. This will take time but is worth it.
8. Have a naming standard for database tables. This will make your life SOOOO much easier.
9. Read thedailywtf.com and don't do anything that is posted there.
10. Write specs for your new developers. Please write specs for your new developers. Don't just say to them 'fix this up'.
11. Make sure code isn't hard-coded to a particular directory. Everyone does this. Fix it. (Might be part of step 7)
12. Create your own standard config files.
13. Have code reviewed by peers. Don't be a bastard but be nice when picking on people's code.
14. As mentioned, comment your code but use the language standard. Java - javadocs, Perl - perldocs, etc. These are cool, but don't get too carried away. Nothing can replace a good spec.
15. Ignore what most people say on Slashdot. (Except for me, of course).
That'll keep you busy for a couple of months! Doing thiswill make you well on the way to having a pretty high level of coding quality. Most companies don't do all of them. Good luck.
1.a Get a test application server and production application server. Yes, you need both. The development server would be the developers workstation.
6.a Formalize the testing process by people other than the original developers.
6.b Write test cases.
6.c Do regression testing. Especially for "transperant to the user" changes.
8.a Have a naming standard for table columns. This will make your life SOOOO much easier.
11.a Where you do need hardcoded directories, externalize the locations in configuration files.
--
- - - - - - - - - - -
I am a programmer. I am paid to produce syntax not grammar. Deal with it.
Great post. Some additions...
1. Use a code reviewer like FxCop for
2. Automate as much as possible with things like Ant or NAnt. The less people do, the less room for errors or discrepancies from project to project.
3. Use something like Cruise Control
4. Make a Utility library so that they have a common place to get repetative processes. (e.g. we have one that validates whether a number and address is a valid store for our company; it is used in 75% of our programs, but only coded once.) You could incorporate some common error handling like log4net or log4j into the utility.
Here a just a few things that come to mind:
1. Version Control - find a VC system everyone can agree and use it religiously, whether for scripts, programs, or even web docs. I've use CVS mainly, with a little Perforce, and Subversion is good so I hear.
2. Coding Standards - depending on how many and what type of languages you have, you'll want to develop standards for how code will be laid out and documented that will make sense and also make it easy for somebody to move from one code base to another with as little trouble as possible. You can be as detailed as like, right down to conventions for naming subroutines and indentation, but don't get carried away or you'll stifle creativity.
3. Documentation - not just documenting code (which any programmer should be doing reflexively), but documenting system flows and procedures. It doesn't hurt to throw together text docs on your more important scripts/programs, outlining where they live, how they're run, etc.
4. The Brain Book - there's nothing I hate more than starting a new job and having to learn all those server names, IP addresses, what I'm supposed to have access to, where in the directory tree the stuff I works on live, what types of DBs we use and their versions, etc. So I developed the Brain Book, where I would write these things down as I learned them, to have a point of reference. It's a good idea to do this for all your major projects, so as new people come on, they can spend less time learning their way around and more time coding.
5. Code Review - everybody's coding style is different and sometimes they don't mesh well or there are divergent opinions on how a particular task should be coded out. Get your programmers together in a room and hash things out as a group. It will provide everyone with a say and may open up some people's eyes to new ways of doing things.
on this particular subject. i believe code complete 2 came out "reasonably recently". that said, were this my task, i'd say the following:
1) document things thoroughly using a tool like doxygen. there is no excuse for interfaces not to be thoroughly documented
2) adopt a standard naming convention. in java, this is easy -- just use the default. in other languages, you'll probably have to make your own up.
3) pick an indentation style. it really doesn't matter which since tools like indent can convert between them almost painlessly. all code that goes into the repository is run through indent to put it into a standard format
4) require that code compile cleanly with no warnings at the most anal retentive compiler settings before it can be checked in unless there are good reasons to ignore the compiler warnings
5) average devs are only able to commit to the "head" fork (or equivalent in your sccs). the code is not committed to the "real" fork until it passes whatever tests you have
6) incorporate tools like valgrind into your testing cycle --- they should come back largely clean. if they don't, things need to be fixed unless there's a really good reason not to.
7) people who check in code which breaks cvs or, upon a code review, are found to not sufficiently adhere to your guidelines owe their dev group donuts.
[ Reply to This ]
We don't need no coding standards!
(Score:5, Informative)
by MythoBeast (54294) Alter Relationship on Wednesday November 16, @08:28PM (#14048949)
(http://www.mythologicalbeast.org/ | Last Journal: Monday September 08, @01:27PM)
Ok, so the subject is misleading. As a C++ contractor with about 15 years of experience in a broad variety of shops, I've been exposed to quite a lot of different coding standards, from severely strict where they told me where and when I can use the spacebar, to the completely non-existent. Of all of them, I have found the GNU coding standards [gnu.org] to be the best balance between the flexible and the legible.
A few other details that I'd like to add. K&R braces were invented, not by K&R but by the guys who typeset their book. It is a severe roadbump to try and read code where the braces are at the end of an if statement instead of vertically alligned.
Try spinal alignment for variables. Most people align their variables like this:
int something;
void somethingelse;
longobjectname theThirdThing;
Those with more of a clue align them so that you can find the variable name easily in a mess of them:
This puts some major space in some cases between names and short type declarations. Try aligning them like this:
longobjectname..theThirdThing;
The problem with this technique is that, if you ever post your code on Slashdot, you'll have to replace spaces with dots and spend fifteen minutes trying to get it to render correctly because SD doesn't support a simple PRE tag.
Other tidbits that have helped. camelNotation rules. Don't use hungarian notation, it doesn't work in a severely object oriented enviornment. Instead, preceed your variables with a single letter that tells you where it's declared. l for local, m for member (of a class or struct), g for global, that kind of thing. I've seen "my" used for member and "the" used for static very effectively, also, but stick to one.
Most of all, good luck. Remember that a lot of people's beliefs in this matter have no foundation except for what they've been doing for years. I have faith in my standards simply because I've seen what happens when you don't follow them, and that's mostly confusion.
Gnu coding standards:
http://www.gnu.org/prep/standards/
