What Workplace Coding Practices Do You Use?

Agent_9191 asks: "Recently I've been promoted to what essentially amounts to a project lead role for every project we do, in house. Since my company has run for the past 35+ years with no form of central IT department, there has been no standards put into place for developers to abide by. One of my tasks is to set up standards in how projects will be implemented and produced. Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code. I've come across some documents in this area from a few sources (of course can't remember them off the top of my head). What practices/standards do you use in your workplace?"

Comments

Comments

[Gyga]

Tell them to use comments in code, and be sure that they make them good comments.

Re:Comments

[Threni]

> somebody changed a 1 to a 2

You shouldn't be using magic numbers anyway - use a #define so that the comments and code stay the same regardless of what the value happens to be.

Instead of

function(1);

try

#define LOAD_DATA 1

function(LOAD_DATA);

Then you don't need to care what LOAD_DATA is.

Re:Comments

[Py to the Wiz]

"if x==456 then //checks for conditional x and executes code if x is true - this is not a good comment if x==456 then //checks to see if x is equal to 456."

Actually, IMHO, those are bad comments. Too much commenting, while not as bad as too little commenting, is still a problem. Writing too many comments is not only time consuming for the developer, but it makes it harder to find the important comments in the sea of crap. Also, if the program is modified, all the comments must be changed as well. This can be a tedious and time consuming process for large projects.

Personally, I try to use comments for parts in the code that might be confusing. Even for a novice programmer, code like if(x == 456) is self-explanatory, no comments are needed. But complicated statements involving many different variables from different parts of the file may be confusing, and likewise merit comments. Also, comments with input/output or precondition/postcondition for functions might not be a bad idea either.

Use comments when you need them, but don't write so many comments that they become useless.

Re:Comments

[Seraphim1982]

I would say both of those are bad comments. Neither of them tells me something that a very basic understanding of the language wouldn't tell me.
I would say a good comment (that is, a comment that I would find useful) for that piece of code would tell you why the statement was important, what is it going to accomplish, and if needed why was it writen the way it was. For your code my questions when reading it would be "why 456?" and "what is going to happen in the following block(s) of code?".

Re:Comments

[republican gourd]

Has anybody written an IDE plugin yet to sign comments? You could for instance have a hash that uniquely identifies comment lines 10-20 and code lines 30-70 as the a 'set' of data that is required to match. Then if the hash of either section changes, flag it as a problem until the hash is regenerated.

Re:Comments

[jomegat]

BOTH of those comments are bad. If a person knows relatively little about programming, he shouldn't be in a position to modify your code. If they don't know what an "if" statement does, they have no business mucking around in my code anyhow.

Comments should concentrate on "why" not on "what." A machine can figure out "what," so a programmer should be able to do that too (eventually). No machine has a clue as to "why" though.

Any time I'm reading through my code and I can't remember why I did something, it's a red flag - that needs a comment. If the code doesn't look like it's needed, but it really is, you need to put in a comment explaining why it's there.

"What" comments should be reserved for the top of a function or largish body of code.

Re:Comments

[joe_bruin]

Our coding standard is a little like this:
Write clean code that can be easily understood by reading it. That is, good variable and function names, try not to make any absurdly complicated statements, and have your comments explain the logic of the operations. As for style, try to stick with the style that the original author started with. And finally, all people who use Hungarian notation are locked in the basement and given menial tasks until they repent their sinful ways.

I hope this helps.

Re:Comments

[OzRoy]

This is something that seems to be very common in commenting. Comments are not there to describe every line of code. Any programmer can see what the code is. A good comment should explain *why* it is that. It should explain what the input is, and what the final output should be.

I looked at that if statement and wanted to know why 486? Why does it execute that block if x is 486? That is what the comment should do.

That said I really need to comment my own code better than I do :)

Re:Comments

[Webmoth]

Write your comments first, then code to match the comments. This way, you are forced to clearly define the input, output, variables and algorithms that will be used in the code BEFORE you start coding. When it's clear in your mind, the coding becomes easier and less confusing; and you have an outline to follow to make sure you don't forget something.

If you write the code first, then annotate, you fall into two traps: "What the heck was that variable for?" forgetfulness, and "It works so stop messing with it" laziness.

Re:Comments

[CausticPuppy]

Our coding standard is a little like this:
Write clean code that can be easily understood by reading it. That is, good variable and function names, try not to make any absurdly complicated statements, and have your comments explain the logic of the operations. As for style, try to stick with the style that the original author started with. And finally, all people who use Hungarian notation are locked in the basement and given menial tasks until they repent their sinful ways

Well that's a good start, with good intentions, but you need to have a standard definition of what constitutes good function names and good variable names. If you have 5 different programmers on a project, you'll have 5 different opinions on what good names are.

Make sure your coding standards are DOCUMENTED.

If it's a java project, the best source would be Sun's java coding standards. A very useful tool for this is Checkstyle. You can decide which rules to enforce (some of the ones enabled by default are more annoying than anything) but if you take the time to get your code to where Checkstyle likes it, you'd be amazed how easy it is for humans to read.

As for my department, we use CVS for version control.
Every time code is checked into CVS, it is formatted by Jalopy. So, it'll look nice and neat the next time it's checked out.
Also, we have a script that does nightly builds, and then emails the result to everybody on the team. So if you checked in something that breaks the build, everybody knows about it the following morning. :-)

We have a regular release schedule. All work is done on the main CVS branch, but when it's time for a code freeze, the new version is branched off and tagged in CVS. During QA testing, bugs are fixed in the branch and the mainline. New features are only added to the mainline.

When we are ready to deploy, we tag the release in CVS. The deployment script checks the tag out of CVS, builds it, and packages everything up into the relevant .ear files which Operations can then take.

This is all a very strict process, but things rarely fall through the cracks this way. If you don't have any processes in place now, it's best to implement them a step at a time. Get everybody used to working with CVS or some other version control, get them used to the notion of tagging and branching, and make sure there's actually a document detailing whatever processes you have.

And lastly, have code reviews every week or two. Review a different person's code each time and make sure everybody on the team is allowed to have input. If you're not at the coding stage yet, have design reviews.

Re:Comments

[BrynM]

Write your comments first, then code to match the comments.

This is why Design Documents are so important. For those sitting there thinking "// checks if x == y then proceeds" is a good comment, the rest of us call this "comment first" idea "planning". It has been working well for coding since the begining and has worked for other things for centuries if not millenia. The most frightening thing to think when handed old code is "My god! They never had more than a meeting of planning for this pile!" Bad or after the fact comments betray a lack of planning every time. Not commenting is almost a downright admission.

When I see code like this, I have turned to my current boss/client and said "You didn't plan this thing very well at all did you?" on many occasions. That question always gets a look of guilt quicker than two teens with no clothes on when her dad walks in. When you explain how you noticed so quickly, you can see the look of "How did I get here? Do I know what I'm doing?" wash over their face a few times over as they think of everything else they are in charge of in the same light... and wonder if their mistakes are always that obvious to others. I remember one PHB wo implemented a "Code Review" the very next day. Fun! Sad, sadistic, pitiful fun - but still fun sometimes.

I wish I had mod points for you Webmoth. You hit the nail on the head dead square. Even countersunk it a little.

Re:Comments

[Anonymous Coward]

Don't do weekly code reviews. Instead, make it a checkin requirement: in order to check in any code, no matter how inconsequential, it has to be reviewed by at least one other dev who knows what the code is doing.
Also, have a simple set of automated test scripts and require that every change must build and pass all of the scripts before being checked in. Also have a more in-depth set of test scripts that are run on a regular basis, and make sure that failures are fixed. Finally, make sure that you have a test org in charge of maintaining the scripts and adding new ones, so that your code doesn't become 'immune' to your tests.

Re:Comments

[Anonymous Coward]

I used to have that feeling about Hungarian too. Until i read Joel's view of how Hungarian is meant to be . There are definitely some times when it is a Good Thing. Not for your str_ThisIsString variables, but to put you in a mindset so that you know whats going on. Its not something to use everywhere (maybe 5-10% of your variables will need it), but if you put it where its needed, its something that definitely helps code maintainability.

Re:Comments

[Tim Browse]

Even for a novice programmer, code like if(x == 456) is self-explanatory, no comments are needed.

You're right - how could it be possible not to know what that code is doing? (The rule is, the only magic numbers allowed are -1, 0, and 1. 456 is right out.)

But then again, don't worry, everything should be clear, right? :)

Re:Comments

[drxenos]

0-127??? Why? The standard guarantees that int is at least 16 bits.

Re:Comments

[Philodoxx]

It's important to comment "if x==456 then..." if it is not readily apparent why x might contain that value. having a comment of "// check to see if x is 456" is counter productive, you're right. A comment like "// x having the value of 456 indicates that the previous operation failed because the CPU burst into flames" is useful, and can help programmers decipher huge decision structures.

Re:Comments

[chachacha]

Agreed.

People forget that code itself is a language. And usually a much more clear and logical one than English. Requirements docs are for explaining complex business processes and code itself explains most of what is going on. That is not to say that comments are not important, but when they exist I want them to be there for a reason. Anyone reading your code is assumed to be conversive, if not fluent in the code language, so comments should explain things such as:

• strange idioms (ie. select((select(FH), $|++)[0]); // autoflush FH)
• reasons for non-obvious choices of algorithms (ie. // we're not using an FFT here because ...)
• intended input/output (a "comment preamble" to a method such as generated by VisualStudio. This is extremely useful for someone following a stack trace.)
• candidates for refactoring (ie. // this method can now be collapsed/condensed ...)
• pitfalls that are likely to trip up an intermediate developer
• (many other valid reasons exist)

Comments that merely "translate" basic code language into english are at the very least useless and often harmful: they bloat the filesize, obfuscate executable lines (I have deleted blocks of apparent comments only to find that unit tests are subsequently failing - the reason? - a single line of executable was buried between 2 dozen lines of commented out code), increase the burden on the maintainer and/or reader who must sort out the important details from the quotes laid down by Capt. Obvious.

Re:Comments

[shobadobs]

I've never understood all this hokery. You only have to obey one simple rule.

The general theory of coding practices: Don't be a moron.

Re:Comments

[BrynM]

nonsense... planning ahead does not equal comments in your code... planning ahead, as you mentioned at first, can be in many forms, and hopefully takes place long before you open up your favorite text editor to write some code...

If you have prelimary docs, then just open them in a text editor and cut-n-paste from them as you go. How hard is that? Don't tell me you're one of those who writes a design doc, only looks at it rarely and imagines "I remember it all" (I'm hoping you're not, you seem smarter than that). That's not planning, that's getting the general meetings out of the way then running away to code off the cuff.

Referencing the documents that the PHB/customer helped write also makes your comments easier for them to understand. Not to mention something the PHB/customer is actually happy to look at (gasp!). It usually makes for better and more consistant documentation - especially if you add in minor "this is for that" line comments where needed.

When it comes down to it, it's actually a lazier way to go in some respects even. It's been a huge time saver and a check against feature creep for me in many cases. Try it and you may never go back.

Re:Comments

[th4tGuy()]

Agreed...

And I would consider attempting to get in the habit of putting the number / constant first. If you accidently drop an = from ==, it will be a compiler error. The other way around can be maddening to hunt down and correct... although a good IDE will at least give you a warning.
EX:

#define UPPER_BOUND 456

if(x == UPPER_BOUND) do_something_useful();
if(x = UPPER_BOUND) assign_upper_bound_to_x(); and_always_evaluate_to_true();

if(UPPER_BOUND = x) compiler_error(); //!

Re:Comments

[lourensc]

if (x == 456)
{
...;
}
this is bad code and no amount of commenting is going to fix it. It begs 2 questions; What is x and why 465? I would recode it as something like this that makes the purpose clear enough that no comments are needed:

const int screenWidth = 456;

if(xCoordinate == screenWidth)
{
...;
}

this way I type more code but less comments.

Re:Comments

[zardo]

It's called test driven development, some people do it without even thinking about it, everyone else is a bad programmer. By documenting your thought process, you help other programmers mature. That's the jist of it.

In addition to everything others have mentioned, for web development you need a good deployment system to compliment subversion or CVS or whatever you use for version control. As far as planning goes, always start with the data model, that is my best advise. Come up with the most versatile data model you can, try to plan for everything, don't just add columns to your existing tables as you go along (or try not to at least). Using a program like inkscape, omnigraffle, or visio can be handy for this, although it takes a bit of practice to come up with useful diagrams.

Usually the data model is the easiest part of the application to convey visually and will lead to the quickest understanding by newcomers. It's usually the first thing I start with when I'm familiarizing myself with something new, whether or not there is good documentation, I'll look in the database first.

Re:Comments

[CountBrass]

You are so lucky you don't work for me, I'd demote on the spot if you produced crap like that for me.

Re:Comments

[fgb]

I get really irritated when developers check in code with sections commented out. If the code is no longer relevant - delete it! If you really need to get it back, get it from a previous version in the source control system.

Re:Comments

[slackbits]

>Using the constant on the left hand side of an equality test such as
>this will cause a compile-time error if you accidentally type
>const int SCREEN_WIDTH = 456;
>if (SCREEN_WIDTH = xCoordinate) { ...

It depends on the language. Any language that has a boolean type is going to give a compile time error to xCoordinate = SCREEN_WIDTH. The only time it will not is if you write if (something = true). But then again that comes down to bad code.

Re:Comments

[arkanes]

None of the above, because you're likely to be using these sorts of checks a lot of times, in multiple places. Write functions (make them inline or macros if performance is what freaks you out) with descriptive names that perform these checks.

if (name.FitsInBuffer() && name.length > 0)

for example. Of course, in this particular case it'd be better to move the maxLength checks into whatever class name is and throw exceptions. These kind of long repetetive checks are prime breeding ground for typos and brainfarts that introduce rare bugs, because the repetetive nature of the code makes your eyes skip over small inconsistencies.

if(Fark.length < maxNameLength) && (Fark.length > 0)
(repeat 10 lines checking different variables)
(Logo.length < minNameLength) && (Logo.length > 0)){

Re:Comments

[Boing]

I agree with you, even inasfar as to say that I think putting constants on the left side is a good habit. However, there is a hit to readability when you do it that way. English speakers read left-to-right, and the subject nearly always precedes the object in a sentence. "if (5 == x)" may keep you from doing accidental assignments, but it also reads the same way "red is my car" would. For me, that means another second or two of parsing it in my head, which breaks the flow of my code review.

Evolutionary Prototyping

[PIPBoy3000]

In my job as a web developer in a healthcare system, I'm all about evolutionary prototyping and other interative methods. There's a handful of big projects where we take a more traditional waterfall approach, but even then it's highly modified.

It's nearly impossible for me to get final specifications from a user until they've actually seen something. Paper is okay in a pinch, but a semi-functioning web application is worth a thousand meetings.

Re:Evolutionary Prototyping

[open_source_dweeb]

But since a cheesy little pull-down-generating server-side script is "programming," there's PHB-fodder about having already done dev work before all of the requirements are described.

The flip side of this is that after showing marketing a semi-functional prototype that is pretty close to what they are looking for, there is often a tendency to assume that the project is near the code-complete phase and that a majority of the resources can be reallocated elsewhere. Just leave a couple of developers on the project to polish up the code and the installation program ... then ship it!

Because of this, I usually like to leave an obvious (from the UI perspective) piece of functionality missing from the functional prototypes. This makes it clear to the management and marketing types that there is more work to be done. They don't really care that the prototype is non-scalable and has the web server making direct database calls, whereas the real implementation would need the web server going through middle-tier business components, data access layers, etc.

Unrealistic expectations

[TheNarrator]

Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code.

Unless you are dealing with trivial projects it will take more than a couple of hours to figure out the code. Even the best documented open source and commercial projects take a few days to figure out.

GOOD code review; Chief Designer at every inspecti

[mekkab]

At every inspection; and of course example code for everyone to mimic the coding style.

And good unit test drivers.

Awesome commentary (both at the top of a package outlining the entire low-level design and at the algorithm level) goes without saying.

Oh yeah, and run spell on your code. I mean, really!

Looking for magic?

[YrWrstNtmr]

Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code.

That is a pipedream. Any project of significant size will require some immersion before a new proj member can get his hands around the particular bit he's trying code/solve.

Standards can be good, but they're not magical. Unless you're trying to generate a group of little robots, everyone has a slightly different style.

Re:Looking for magic?

[waldomaniac]

Good call. Waste a couple of hours?... How many hours are you going to want to spend on the standardization process? And enforcing it? Beware the tools of micro-management... standardization, time-keeping, the dark side are these... Personally, I'm down with the tagline I saw one time:

Comments should be banned - it was hard to write, it should be hard to understand.

GOOMOALMWIP/GOOMCALMWIP

[Martin Blank]

Get Out Of My Office And Let Me Work In Peace

or

Get Out Of My Cubicle And Let Me Work In Peace

This applies mostly to the people that come in and have to inform me of their new cat, girlfriend, boyfriend, computer, game, TV, kitchen, car, shoes, and/or midlife crisis (and that's just the top of the list).

A request on the part of the devs under your control: Don't implement a new paradigm every time one comes out. From extreme programming to agile programming, from scrums to design workshops, find something that works in your particular case and stick to it. Your employees will thank you for it (at least in the long run by not planning your demise in the parking lot after the fifth methodology change that quarter).

loose standards are best

[Anonymous Coward]

If you dont allow people to code the way they naturally can, don't expect any amazing code or new ideas. Their code may also have bugs. Don't buy all the standardizaion hype.

So if you are going to have standards make sure they are loose, and pertain mostly to external interfaces etc. requiring comments or code descriptions or something. I am telling you the worst thing for a project is frustrated programmers because they will make shortcuts in the code. Trust your developers ..u shouldnt be hiring 'em if you arent going to be trusting 'em.

Coding Practices

[Billosaur]

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.

Specs, reviews & tools are the real key

[VisualVoice]

From my experience managing many multi-million line code projects for many years, its the tools (source control, bug system, langauges) and a standard documentation templates (market requirements doc, product requirements doc and detailed design document, unit test document) that are more important to standardize than coding guidlines. Sure everyone should follow a good variable naming convention (hungarian or equivalent) and heavily comment each function's purpose, but beyond that you can waste a lot of team time on arguing about idententation, and micro-commenting guidelines.

Also key is a standard process of developer peer reviews. All developers should have peers review specs. New or mediocre developers should have their code peer reviewed. Proven developers can be excused the code review but not the spec review.

Experience counts

[canuck57]

My suggestion is get someone who has done this in a structured and successful environment. Otherwise developers will roll you over and your projects will be late, over budget and buggy.

I have seen it so many times where an internal inexperienced person jumps in the saddle without mentorship and guidance in the areas of software development (NT or UNIX) and systems management not native to the environment. And I have seen how long companies suffer with the problems created by this and how much it costs companies in the end. It makes a $1000 per hour consultant look cheap.

A good example is code management. Very few IT shops have it. Why? No one wants to know who checked in the buggy code! But few developers want such tools, especially the microwave generation. But at least when your caffeine isn't good enough and they move on you will know where the source code is.

Sounds simple? Not really, there are hundreds of issues like the one above. And it can't be taught quickly.

So get a consultant for 6 to 12 months that has done this, listen and learn and you will be off to a fast start.

Pottery Barn rule

[lanced]

The pottery barn rule comes to mind: you break it, it is yours. Or at least that's the way it is when I am tweaking the legacy code.

My boss on the other hand, it's more like the bull in china shop. Heck if I know how he got in there, but I know there is going to be heck to pay in the morning.

Re:A Good Coffee Break

[Eberlin]

A good break in general will clear the mind often enough to get unstuck on some problem. Coffee is optional. I often find that walking around (even just in the room) with a stress-ball, and talking aloud to myself will reveal solutions that wouldn't have otherwise shown up if I were buried too deep in the code.

That and something to scribble on. Either lots of paper or a whiteboard. Whiteboards are cool for getting your thoughts organized. Unfortunately you can't make printouts afterwards...but a good digital camera snapshot of a whiteboard will give you enough to remind you of what you thought up.

The general hint -- give yourself some time to step back from the problem. There are times when it's good to bury yourself in the code and times when it's better to think things through away from the code.

Programming Standards

[clockwise_music]

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.

That's Like Scrum...

[Greyfox]

Scrum and Code Reviews are all well and good but people who've never done that before don't know what to expect, so they tend to be all over the place with their comments. This leads to code reviews where your code is nitpicked over every little thing and scrum meetings that grow and grow until they take 2 hours out of every day to complete. Neither of these things are beneficial to productivity.

I find that a good standard for code reviews is to assume that the programmer knows what he's doing and I don't try to push my political agenda in them. If you want to have a passionate argument about hungarian notation or putting braces around if statements that only execute a single line of code, the code review is not the place to do so. If you think a data structure he used isn't up to the volume of data you'll be running through the system, THAT's something to bring up in the code review.

You can require comments in your code all you want, but I find that you inevitably get something like this: "a++; /* Add 1 to a */" With no indication anywhere of what A is or why you would be incrementing it there. I would propose power stapling the offending programmers in such cases, until they learn not to do that anymore. I would say remedial English classes, but even I am not THAT sadistic.

Peer Review Often

[ear1grey]

Establish regular peer reviews: regular, as in daily; and not just when the library is finished and ready for delivery.

Peer reviews encourage developers to describe what they're doing and why they're doing it (not just conceptually, but at the code level) so deeper awareness of whole systems is fostered.

This can lead to projects with less redundancy, and greater integration. It also helps ensure that code will pass any human driven acceptance tests that the commisioning agent may stipulate.

An additional benefit is that utilisation estimates are improved because as developers get better at describing what they're doing, they become better at describing what they plan/need to do.

The canny manager will schedule the peer-review session 30 mins before lunch, recognizing that it gives developers something to discuss as a group whilst eating.

35 years says a lot...

[clambake]

I dunno, there aren't too many software companies been around 35 years and still going strong. I'd say go with what's been working. The best "coding standards" are: simplicty, adaptability and readability.

Let programers do what they want. When somone complains that XYZ is hard to read, then it's his job to refactor that code into something that is easy for him to read. Assuming you have the tests you should have written, he'ss have no trouble doing this. If the tests aren't there, then write the tests first so you know if you broke what's already there.

Don't comment your code. Make the code so damn readable that a comment is superfluos.

Above all, don't make rules you can't break on a whim, but do make rules as you find them helpful. Go with what feels right until it stops feeling right and then fix it.

The first person who says something unhelpful as "your code doesn't comform to our company mandated brace alignment standard" gets fired, but only after he's shown what a modern IDE looks like and how well it autoformats the code to any brace standard he cares to think of.

Re:code complete has some good things to say

[masklinn]

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

5 is not that required since most modern version control tools are able to run scripts on your data before/after the commits.

In that case, the indentation cleaning, compile test and full unit-testing of the modified application could be done automagically at commit, with commit refused if code doesn't seamlessly compile or if any unit test fails (any code change would also, naturally, require the concurrent commit of the modified unit tests for the code).

Worry about what not to do, too

[Rocketboy]

Many (many) moons ago I worked for an IT manager who's explicit instruction was, "don't use arrays." He didn't understand them and, therefore, they were bad.

The moral of the story?
 

A. You are not the font of wisdom. If very lucky, you are the point of the pen. Rule carefully.

B. Don't make standards based on what you learned in school. Base them on what you learned in real life.

C. If an Old Fart tells you that one of your edicts is stupid, don't assume that they're resistant to change just for the sake of being crotchety. Maybe they learned something useful over all those years and all those lines of code.

Re:What a question!

[geekoid]

I would write people up, and see that it was reflected in there perfomance review.

You work for me, you do it my way. If you think your way is better, present it to me and tell me why. "Cause it's the way I do it " doesn't count.
I'll train you, I'l give you time to set up your editor so it automates whatever you need automating. I'll mentor you, have other developers mentor you. But there is a line where I expect the developer to be up to speed.

Standards

[umbrellasd]

Current place we have a corporate naming convention document which addresses the various environments that we work with. Formatting conventions are unspecified, so everyone in our group does what they want to do. I typically use an indenting scheme that is pretty standard for most .NET articles that I read or code that I encounter (because much of my work is .NET). For the most part, we just focus on being consistent to our own approaches and the most important thing is being accepting of different ways of doing it.

I think the most important policy is to slap the guy that says, "I like tabs more than spaces" or "I don't like the way you indent" or "I hate the way you put spaces around ('s".

Honestly? These people have too much free time. People use a variety of conventions and I've seen pretty much all of them. As a senior developer, I just take everyone's idiosyncracies in stride, even when they name variables retarded things like: n, vt, pkq, and rsptln.

If I can deduce what they are doing easily, it is no problem. If I cannot, I make them explain it. If they are not around anymore, problem solved. I rewrite or have their stuff rewritten in a good way, since the stuff was 99% likely to be utter crap anyway, and move on without a moments hesitation.

I've worked on a lot of large codebases and I've never encountered this idea of, OMG this code is so archaic that I cannot possibly decipher this person's intent--and believe me, I've worked on some crazy ancient crap. My obligatory developer arrogrance leads me to state that people that cannot figure out code because of coding conventions are weak developers. Anyone that has slogged through the convoluted "efficiency" of Knuth or the a,b,c,i,j,k madness of Wirth can figure shit out.

So anyway, if you have the authority and your people are actually willing to go along with a standard without a huge hullabaloo, then just pick any standard (you'll get way more mileage from just sticking to a consistent convention no matter what it is). If people are going to make a big deal of it and it is difficult to enforce, just deal with it individually and tell people to write sane things. Their coworkers will provide quite good feedback if they are producing shit, and that's where you really need to step into your lead role and work out a resolution.

One of your best tools for a standard is to create automation to enforce it. Get yourself some prettyprint scripts that you have run on all source that is checked in--in fact, get your developers the same tool so they can run it on what they check out to print it the way they like it. (Of course, you only want to check the source in with the standard pretty printing or diffs become atrocious, but that's technical stuff for a different discussion.)

Bottom line is that whatever you can automate in the way of conventions is a win because then it's completely automatic, difficult to bicker about (two coworkers can't very well bicker at each other when it's the prettyprinter's fault, so they can only come to you and you have authority to resolve the issue right quick, whereas they could just engage each other in an endlessly unproductive slugfest if they are coding by the convention of their opinion), and if people want a change it goes through you and you have a strong argument for--"if it isn't broke, don't fix it".

Kind of a ramble, but after many years this is my take on standards. Use a convention if it is convenient. If not, play it a bit more loose, but be firm on snuffing out those annoying neverending debate situations.

That said, one factor that is relevant is the type of work you are doing. I'm assuming from what you said that you have some flexibility to structure as you like. If for instance you were subject to government or other agency auditing (my current company is), then the loose method is not going to fly, but on the other hand, you would probably already know what conventions you needed becaus

Geek minds

[eric.t.f.bat]

The best description I've ever come up with for the Geek mindset is this: a Geek can hold a complex structure in her head and manipulate it with ease. A History Geek can hold the structure of a historical event and see motivations and causes from every angle; a Carpentry Geek can plan an entire piece of woodwork and see every cut and join vividly; a Programming Geek can hold a program's structure and its data and event flows and manipulate it as an idea.

Someone commented that the difference between Microsoft and Google is that Microsoft programmers are holding concepts the size of "If...Then...Else" and Google programmers are holding concepts the size of Bayesian filtering; thus, Google's Geeks are better at making big, coherent plans without getting lost in the details. It's not 100% true across the board, but it's an insight.

As a Project Manager, then, your job is to:

1. Allow your Geeks to transfer the concepts from the screen/page/whiteboard into their heads; and

2. Allow your Geeks to hold those ideas easily once they've got them.

Step 1 is a bandwidth issue: make the "inputs" more efficient by, for example, giving all of them dual-head monitors and high speed printers, so they can get lots of code into a usable format for reading (some of us prefer printouts; others just need vi/Emacs and a flicker-free monitor). Step 2 is a quality issue: Geeks who have to hide in headphones or run away to the park to read because of ringing phones and nagging managers are NOT going to be able to do their job.

And with any data pipe, throughput is more a function of time rather than pressure. So your dream of getting your programmers up to speed in minimum time really is -- pardon the pun -- a pipe dream. They won't be any use to you if they don't have the time to learn the systems they're working on.

I recommend the Mercury project model

[ralphbecket]

Mercury is an industrial strength, state-of-the-art
compiler for a declarative programming language
comprising some half a million lines of code. The
project has been running for over ten years with
multiple developers working at any given time, some
of which are in different locations.

Key aspects of the development model are:

(1) Use a good source code control system (we use cvs,
but are considering svn).

(2) Add at least one test case for every piece of
functionality you add to the system and for every bug
that is discovered during use.

(3) Use a robust, automated build-and-test system.

(4) All code changes should (a) compile, (b) not break
any test cases, and (c) -this is vital- pass peer
review on a mailing list.

(5) All code should be adequately documented. Every
change should be accompanied by a log message explaining
the rationale for the change and what the changes were
and a unified source code diff.

(6) Have a common coding standard for things like
naming, layout, commenting, and preferred idioms.
Shoot any coders that use more than 79 columns in
their code.
Avoid complexity and cleverness unless it is absolutely
warranted.

(7) Code should check all error conditions. Exceptions
are rarely a good error reporting mechanism.

(8) Have nightly builds and test runs.

(9) Your watchwords should be discipline, cleanliness,
simplicity.

-- Ralph

Fundamental coding truths

[WiMoose]

In addition to some of the suggestions made so far I would add a good automatic regression-test system which runs every night, and reports problems (build failures or result diffs). I've made mine so they "find the guilty" (whoever committed code since the last good regresstion test).

I recently put together a list of Fundamental Coding Truths after musing about this topic and why it was so hard to plan software development:

1. Software is not at its core a collection of a few clever algorithms.
      Rather, it is primarily (in the ways that matter) a huge collection of arbitrary
      choices and random implementation details.

      The algorithms that consititute the mathematical/logical basis of a piece of software
      are an important, but very small (eg: 1%) and relatively very simple part
      of the overall code.

2. Code complexity is pretty much exclusively determined by the (combinatorial)
      number of interactions between pieces. Each interaction requires at least one decision
      and usually many more.

3. Because of #1 and #2, deep, intimate familiarity with the code (this vast
      collection of implementation details) is only ever fully knowable to the original
      author(s) who made these uncountably many, mostly arbitrary decisions.
      (Familiarity by secondary authors/maintainers comes primarily from
        re-writting sections of code.)

4. Because of #3, programmers are not interchangeable. The efficiency with
      which a person can navigate the code, implement or even imagine changes
      is almost entirely determined by how familiar they are with these many, many small
      details. The ratio of efficiencies between a primary author and another
      equally talented coder is very large (eg: 100). Because of this, the original
      authors of a section of code are usually the only ones who are ever able to efficiently
      modify or restructure it. This becomes rapidly more true as the the size and
      complexity of the code increases.

5. Because of the complexity of code (the number of interactions and interdependencies),
      debugging and maintenance constitutes the vast majority (eg: 99.9%) of the work
      required by a piece of software over its life.

6. Because of the complexity of code (number of interactions between components), it is
        very hard, if not impossible, to predict with any accuracy what will be involved in implementing
        a given change. Even for original authors, unintented side effects are almost inevitable, and
        the primary determinant of the length and difficulty of a task lies in finding and rectifying
        unintented consequences or unforseen interactions. Because of this, the uncertainty in the time
        it will take to execute a change is very large.
      (eg: 10x range in 95% confidence limit of time estimate, say 1 day-2weeks).

7. Because of the complexity of code, bugs are an inevitable byproduct of writing code. It is hard
        to predict how long it will take to find and repair bugs as that depends on how many side effects are
        involved, which is not known until the repair is done and "fully tested". The only way to avoid bugs
        completely is to not write code. There are things that can minimize bugs or speed up finding/fixing
        them, but they will always exist.

Coding Style

[Anonymous Coward]

This is a subject near and dear to my heart. I have a history of coding in small shops, from 1 to 7 programmers. I currently work with two other programmers at a company that has had 4 programmers before us that are no longer available to us. My coding style is very different than my coworkers'. My code is very dense, with few comments, because I believe the code is the comment, and frankly, I think if a compiler can understand it I should be able to also. But that's not important here. I think it is useful that we all have different coding styles. In an environment like mine that has only a few players we learn each others style and know who did what just by the way it looks. It's also nice to see where one person has modified another person's routine.

I love good variable names and statements of purpose and all that, but I think pure conformity is counter productive. Whatever guidelines you put in place, if you allow for some differintiation between authors it will help with the debugging later.

Standards are irrelevant

[dpbsmith]

It's funny. I work very closely with two other programmers, although we work on almost disjoint bodies of code. Our coding styles vary widely. One of us uses Hungarian notation, one of us does not, one sometimes does and sometimes doesn't. We use different indentation styles, different nesting styles, different personal styles for naming variables.

And you know what? None of us have any trouble at all reading or maintaining each other's code.

Why? Because we're good programmers; because we _care_ about what we are doing, we take a long-term approach, and management judges us by our long-term track record and doesn't look over our shoulders micromanaging how many spaces we indent.

And we all write LOTS of comments, but we comment the things that need to be commented, not just pro-forma and CYA stuff.

You want documentation, not coding standards.

[oneiros27]

Don't get me wrong, coding standards help too, but by the question:

Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code

I couldn't care less if people are using tabs / 2 space indents / cuddled elses / whatever formatting crap.

Even how you name your variables vs. functions vs. methods vs. objects has very little to do with being able to jump into a project, so long as people are consistent. What's more important, is to maintain good documentation, so that someone has some clue what the relevent files are, and what the overall logic was in how the program / general modules / etc are laid out.

No one is going to be able to jump in and start modifying code on a moment's notice. On a large project, spread across multiple developers, it might take a week or more for someone to have a grasp of what needs to be done, why it's being done the way it is, and what the implications are to change things to the way that they think is better. (I consider unit tests to be a form of documentation -- given a specific input, I expect the given result)

  And let's not forget the whole mythical man month -- tossing in another developer at the wrong time may screw up the existing developers if they get pestered by the newbie. That's why I try to keep documentation explaining what the purpose of the project is, known outstanding issues, how the program is laid out, all of those sorts of things that a new developer would need, should I get reassigned, fired, given extra help, or just give up and decide to quit.

A ticket tracking system, and some centralized documentation repository (might be a wiki for multi-person projects) can really help you get a handle on these sorts of things.

If you want actual programming tips ... take a look at Damian Conway's Best Practices article for perl.com (or his book) ... much of it applies to more languages than just Perl.

Re:Comments lie

[rs79]

" and finding out that those things no longer apply because somebody changed a 1 to a 2."

Comments lie. Code never lies.

You don't have to come up with anything...

[Lairdsville]

If your company has been doing development for 35+ years in multiple projects, there is certainly a body of knowedge and culture of development that has evolved over the life of the company. I doubt that you could just 'come up' with anything better yourself, so I think your goal would be most effectively achieved by collecting and organising the information that you have all about you.

I achieved a similar thing in my company by setting up a wiki (I started with Twiki and then we changed to Confluence) with a basic skeleton that I wanted have fleshed out. I even got our developers to define the skeleton, they all knew what we needed, code guidelines, review methods, development procedures etc. Now all I have to do is spread the word about the existence of the wiki and watch it emerge!

Re:My boss doesn't care

[dubl-u]

And the original poster should consider the benefits of something nearly that loose.

Don't arbitrarily set up standards. Ask people what problems they have. Tell people what problems you're facing (e.g., you need to be able to move people more easily between projects). Then ask the developers who don't have those problems what they do. Feel free to toss in your own suggestions, too. But let them talk first. And let the developers decide how to do the work as long as they address your needs.

Remember that you're not working in some Taylorist 1930s factory where you have to specify every motion. Creative work, which is what your developers are doing, is utterly different than factory work. (See the book Artful Making for more info on that.) Treat them like professionals and they'll act like professionals.

Re:Magic Numbers

[WushuJim]

In addition to that, don't hard code values into variable names such as making a timer variable called fifteenSecondTimer.

What we do

[InAbsentia]

Small shop of 12 coders about 98% java code. Total source under version control 270,000 lines of code plus 130,000 lines of unit tests. We use cvs for source/version control.

The most important thing is AUTOMATE everything that you can.
We run a cycle where we do an automated checkout every 15 minutes. This is compiled and the checks below are done on all packages that have been updated or which raised errors the last time. Every three hours we do a zero base checkout and run tests across everything including running all unit tests. We also then do a complete construction of installers etc. for the products we ship and run tests on that (rather than in the developer environment). We also checkout across multiple platforms and run the unit tests on these (this is a bit more irregular). The results are collected on a company internal website and errors cause a real-life set of traffic lights to turn red (everyone can see them).

The things we automate include:

• style checking (checkstyle) and some other similar packages
• spelling
• javadocs on all publicly accessible methods
• running unit tests
• we check the unit tests by running a mutation tester which checks how well the unit tests cover the code

There is more to testing than this but this certainly deals with the low level coding stuff well.

partially agree

[xswl0931]

If code is written well, it should have few comments as the logic should be fairly obvious. In the case of if (x == 456), this should really be something like "if (STATUS_BUFFER_FULL == statusCode) ..." now it's obvious what is going on. Descriptive variable names and method names mean less comments are needed.

Re:Question about Hungarian Notation

[joe_bruin]

Hungarian notation has its (extremely limited) uses.  The reality is that it turns code into garbage.  Go ahead, read aloud the lines of code below.

// the old c style
if(cur == last) rec->tag = name;

// camel case
if(currentKey == lastEntry) Record->keyTag = userName;

// hungarian
if(iCurrentKey == iLastEntry) prRecord->m_pszKeyTag = pszUserName;

Now imagine discussing them with your coworker.  Imagine thinking in your head "What should I do if prRecord->m_pszKeyTag is NULL?"  Humans are good at symbolic manipulation.  Giving something a name makes it easier to deal with.  Giving something a label that cannot be easily manipulated in language (spoken or in your head) severely hampers the ability to think it through.

The argument for Hungarian is usually "but it lets you know what the variables are".  This is the maintainance programmer argument.    This argument rarely makes sense in reality, unless some very bad programming is involved.  First of all, if you do not understand the current code you are about to modify, you should *not* be modifying it.  If your maintainance programmer is just going to have a look at two lines of code, add a third in the middle, and hope for the best then you are truly fucked.  He has obviously not understood the code enough to know what the consequences of the modification will be.  The reality is, if your current logic unit is such a monstrosity that looking up the types of your variables is a burden, and your variable names are so poor that it is insufficient to infer at least a basic understanding of what is going on without having to resort to prepending types, you should probably step away from the keyboard, turn off your computer, and tell your boss that you had an epiphany and will be pursuing a career in French fry development.

Some of my rules

[gregm]

I'm not really one for coding standards, just make each person maintain a certain level of consistantcy and make damn sure they make good comments. You might want to institute some common variable naming scheme. Here are a few rules I've come up with over the years.

1) Thou shalt NOT make the user re-enter data
2) Waste not clicks for they are precious
3) Thou shall not design a screen that hath no purpose
4) Move not your bits about the screen like a drunken stripper
5) Gulp not your data but merely sip... as it makes reguritation less lumpy
6) That which the user doeth the most, shall not be obscurred by that which he doeth least
7) Dress not your screens with vain and lustful colors that are without purpose
8) The user is the one true god and thou shall hold no gods before the user
9) The user is a friggin idiot
10) An image that measures 16 pixels across and 16 pixels along it's length is rarely worth one word

G

I keep my own log book for programming

[Cappadonna]

I'm a freelance developer for a day trading firm and a PACS/RIS** administrator for municipal hospital, so most of my projects involve really massive planning for large amounts of data. Whenever I start a new project, I right every little component in a big lab notebook. I even right out major snippets of code, line by line. This helps me in several ways.

One, when I start plunking away at the keyboard, most of my ideas have been muddled through and I'm not wasting time fumbling through books and websites to find answers. I can also note what ideas did and did not work. Also, since I am typically juggling mutliple projects, it helps me keep track of what I've done and what I have to do.

Second, I've learned to keep it for review. Basically, I learned at my last job that documentation can save your butt, especially when working with nurse manager who still can't find her archives folder in Outlook or trying to explain how archaic software works to management when nobody has even looked at the source code in 7 years. Its a picture into my brain and its a log of where things have progressed for a give project.

Third, my notebook has served me are my only way to figure out what the heck I'm working on. Essentially, I've always been given a massive system to rework/hack/redesign that nobody else bothered to figure out. My notebook is my only guide to solving problems, since its my only reliable reference.

Fourth, a journal can double as a weekly to do list. Alot of times, I have so much crap going on running my system that I forget what the hell I was working on. So, I often write down 10 projects or assignments I need to do within two weeks and cross them off as I go along.

And finally, it keeps me from having to write the same things twice. Often, I can use code snippets, data structures and old work flow schemas in other projects. that's really helpful when you're up until 12-1 in the morning hammer away at some God awful perl script and you need to get everything finished by the weekend.

** PACS and RIS stand for Picture ArChiving System and Radiological Information System, respectively. They are two ancillary systems that hospitals now use to save X-ray, CT, MRI and other images of the body.

Re:Comments lie

[mabinogi]

That depends on what you expect it to tell you.

Comments can lie, and code never lies about what it does, but code doesn't tell you anything at all about what the author intended it to do. The comments are more likely to give you a hint, and at the very least if the comments and the code agree, you can probably be sure it's right. When the comments and the code disagree then you know that at least one of them is wrong.

Use automatic code formatters

[mophab]

Use indent for C and C++
And Jalopy for Java.
Formatters are available for most languages.
Decide on what all of the options are for each formatter and make
a script available that runs the formatter with the appropriate options.

Require that automated formatters be run before code is checked in.

It is easier to read consistant formatting than your favorite formatting.

As much a social/managerial issue as a tech one

[crucini]

First of all, how many developers do you have? Few enough to fit in a conference room? How many languages? Do all the developers know all the languages, or are they fragmented into language communities?

The first step is to assess the current situation - what coding practices are currently in use? What do the developers want? Can you roughly group the existing codebase into various standards, plus a pile of incoherent crap? Is it worth while rewriting the crap portion to the new standards?

Second, decide what level of standardization you want to achieve. The more detailed your standards, the more difficult and risky. You will probably make some wrong decisions, and they will irritate developers now or in the future. However, if all your developers code in the same language, and several of you are experts, you may be able to write detailed standards and get it right.

Third, identify relevant references. If you're working with Perl, Damian Conway's Perl Best Practices is a good choice. In C++, Meyers' Effective C++ series is good.

In general, micro-standards will not be successful. Instead of trying to make everyone use the same indentation or something, you'll get the most bang for the buck by focusing on high level issues. For example:

1. Require at least one Wiki page for each piece of software; in addition to any docs on how to use the software, this is a page on how the software works internally.
   
2. Keep code units to a reasonable size, with a clear interface. Reduces chaos, and lets you rewrite one unit from scratch if it's written horribly.
   
3. Require a peer code review of each code unit. Persuade the reviewers to read the code before the meeting so you get more than off-the-cuff comments. Experienced programmers may disagree about indentation, but they generally agree about things that really shouldn't be in your code. Comments from these reviews may crystallize into a de facto standard.
   

Good luck.

Code cleanly and remove comment

[oo_waratah]

replace a stupid name with a sensible name:

      messages_processed++;

This actually makes sense without the comment.

Re:Code cleanly and remove comment

[rkww]

replace a stupid name with a sensible name:

messages_processed++;

That's still got potential for confusion - it could be a 'we've finished processing the messages' flag, which obviously should be a boolean, but somebody else wrote the code, so we can't be sure.

totalMessages++;

would be better, but it's still not perfect. Sometimes the hardest part of programming is creating meaningful variable names.

Re:Comments lie

[bullgod]

But code can only tell you the how it can never tell you the why. That's usually more important
I once came across a ~1400 line function of complex maths transformations with one comment

i++ /* increment i */

What's i? and more importantly why increment it?

The beauty of slashdot :)

[KZigurs]

Aaah, what a beauty. The real questions that should concern this are more in lines of the following:
- What is a development envorement?
- What is QA?
- How can I test code before putting it on production?
- How can I plan for and track team progress in development?
- What kind of documentation will I need?
- What is a process?
- How do you declare/manage process?
- Who is responsible for builds, who writes specs?
- Do we have separate QA team?
- Is there any testcases?
(silly, I know, but shows the scope of his position a bit)

YET we have 300 comments + discussion of using or not using hungarian notation in naming variables.

Perrfect! :)

Re:Comments lie

[kibbylow]

Comments often get in the way of code readability. I often get annoyed looking at comments like these:

// initialize index to zero
index = 0;

// if string is null return an error
if (string == null)
    return error;

// get the next index
index = getNextIndex();

Comments should be reserved for describing functions and non-intuitive variables or code blocks.

I find that having naming conventions for variables, classes and functions is very important. Using proper names makes reading the code so much easier and eliminates the need for useless comments like the ones above.

I remember back in my first or second programming course they said, "you should be able to remove the code, read the comments and fully understand what the code is doing". I never agreed with this statement.

Re:Joel on Software

[Anonymous Coward]

His best skill is self-promotion.

Re:Joel on Software

[measterbrook]

> Plus, he argues passionately for paying programmers well & giving them exciting projects, but in at least two cases he hired interns to start his company's most interesting apps.

That is because Joel has fallen into the legacy vs new trap.
Legacy code is difficult to maintain and only your best and most experienced programmers can work on it without either braking it, making it worse, or doing it very very slow. In comparison, writing new code _seems_ relativily easy (can you hear the alarm bells?).

So if you have to put your best programmers on the legacy code, everyone else gets to write the new code ... badly (but you don't realise this until maintanance time). The new code becomes legacy code, which requires your best programmers, which leaves the rest for the new new code. And the cycle continues.

There is no easy answer, pair programming helps, but requires more staff. Not many managers understand the "pay a bit more now, collect the big reward later" way this works. Good experienced programmers are expensive, young inexperienced progammers are cheap if you only consider how much you pay them (and not how much you have to pay to sort out the mess later using your expensive experienced programmers).

It works for me - I make a living out of fixing bad legacy code. I don't get to work on the sexy new projects, the youngsters do, creating my future employment needs... and so the cycle continues...

In addition...

[SeanDuggan]

The general theory of coding practices: Don't be a moron.
More importantly: Don't be too clever.

It's when people try to get clever in their coding that it gets hard to read. And, quite frankly, that's the code that generally breaks most easily.

Re:Comments lie

[xaque]

but what if aliens replaced your glass tubes with dynamite when you weren't looking?? it's better to just not code at all, and spend your life hiding in a cave armed with a pointy stick.

You should still know

[bluGill]

I hate Hungarian because you know the type from the context anyway. You don't do addition on a list. You don't do foo[bar] on a real.

A variable should encode everything you need. A variable strSql isn't as useful as selectFoo which tells you what you are doing with the variable. The the variable contains sql is obvious from the context where you care about the contents, and you tells you what it is for where you don't care about the exact contents.

Re:You should still know

[bluGill]

Sadly strSql isn't a made up example - I was looking at code that used it while I wrote that reply.

qryLogin, is useful because it tells me what is going on (even more than the replacements I came up with). If the prefixes have meaning I do not objects. The datatype however is rarely meaningful.

Where you use data type prefixes is with a variable like userID. Is it an int or a string?

You do not care what type userID is! Does it make sense to do userID + 1? No, so even if it is an int you don't treat it like an int - it is a userID. If userID was a string, likewise you do not do string manipulation on it, so it doesn't matter that from context you are unsure what it is (though I would object that it should be userName).

Code Review is Good

[oldCoder]

Publishing coding standards about comments, variable names, subscripts vs pointers and indentation tends to generate a document that dies after 3 months. A waste.

Have an opinion on all the above but some of your best coders might disagree. And might not agree with each other.

Code reviews for bugs, design, format, readability et cetera are a good way to improve code quality and application quality. Code reviews are very difficult to perform and very difficult to manage.

The idea of code reviews is so old that the older recommendations say you should review before your first compile! Find a newer guideline. The most important guidelines are about the emotions involved in code review. People can get very accusatory and very defensive.

One way of doing reviews is pair programming.

You will find as you go along that many managers and customers simply do not want higher quality if it delays first release. Chew on that.

Think in advance what you will do if you find you have a good coder that nevertheless produces code that is too hard for others to understand. Rather than canning somebody, perhaps you can help the coder to express him or herself more clearly, and help teach the other one to read code more effectively.

Code reading is a specific skill and may be a specific natural talent. That is, different from the skill and the natural talent of code writing.

Code reviewers, testers, managers, and others often have a legitimate need to add comments and/or links to production code ("bug #1234 crashed here", and "I don't understand this", and "90% of the cpu is used here"). It would be good if there were a version-control and text-editing system that allowed non-coders to add "yellow sticky notes" to code -- without breaking the build!

Re:Question about Hungarian Notation

[P3NIS_CLEAVER]

Tight scoping of variables negates the need for HN.

Re:Question about Hungarian Notation

[ColdSam]

I rarely use Hungarian, but your reason for not using it is awfully contrived. In your example how would you ask the question using your own naming convention?

"What should I do if open paren capital R ecord dash greater than capital K ey capital T ag equals equals null close paren?"

If we used Hungarian and I were to ask the question of a coworker, I would of course leave off all the crap (unless it were relevant). Humans are good at that and Hungarian notation makes it pretty easy to spot the "real" name (just skip everything until you get to the first capitalized letter).

You may have a point if you are instructing a coworker in what to type into his editor, but if that's the case you probably have bigger problems with your development team.