Slashdot Mirror
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?"
If you really are starting from ground zero, I'd suggest setting up a repository such as SVN as a good first step. Couple this with a good template to set up standard locations for documentation directories alongside the code trunk and branches (and any other resources your projects requires (images, sound other media). Make sure everyone uses the repo - even if you have to spend a day leading people through it - you'll save time later. This also ensures your projects are backed up (so long as everyone checks in at the end of the day at least), and screwups - such as deleting the wrong directories and forgetting about it for weeks can be reversed.
Obviously there are other issues such as naming conventions, useful comments etc, which are often neglected in small projects, but become more important as more people work together without wars breaking out!
Find out your teams individual strengths and preferences - there's no point trying to hammer everyone into the same mould - some people will naturally gravitate toward, and excel at certain tasks. It's important for efficiency and general happiness that this is taken into account when allocating resources to a project.
Code, Hardware, stuff like that.
Yeah, but Joel's an ass. Have any of his worshippers here on /. actually *used* something written by Fog Creek or whatever? FogBUGZ, a web-based bugtracker, seems to be his one claim to fame, & it's terribly mediocre. I mean, mostly it works, but the search function doesn't, the UI is inconsistent, & while you can define filters (such as, "my open priority-1 bugs"), you can't share them, which makes them nearly useless. Joel writes a good spiel, but when it comes to coding, his company ain't the shit.
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.
Dude needs to work on his street cred.
Visual Studio has one called "Ghost Doc" that we use. Also, microsoft has some macros you can download that will create documents for constructors and for any exception within a method. Using these two together, and you have a pretty standardized comment collection that can be compiled by NDoc (the .NET version of JDoc for Java). I have a really good one for Eclipse, also, but can't remember it of the top of my head.
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.
What's amazing is that you can say that in two sentences, and most web developers here will completely get what you mean... and that traditional managers (of developers) will get incredible hives and seriously rethink your annual bonus for uttering such heresy.
My favorite flavor of Not Getting This are the managers or customers that want you to mock up some screen shots for discussion, and are happy to pay for you to do so in Visio, or a paint program, etc... but if you instead actually whip together some HTML-based forms (much of which can eventually go towards further prototyping or actual use), you've opened the door to arguments over charges for having "jumped the gun" on the programming cycle. Never mind that I can produce conceptual mockups that actually render on a browser faster than by most any other means. 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. Oh well. I'd rather write off a chunk of the project's proceeds than try to hammer out all of the requirements on paper first. In real life, with projects that must go from "I saw this thing when I checked out at Amazon" to being functionally bolted onto an existing web presence in a matter of a dozen man-hours, that's frequently impossible.
Don't disappoint your bird dog. Go to the range.
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.
There is lots more to coding standards than just comments and style. Where I work, portability and maintainence are of high concern too. Certain rules, like no hard-coded values such as 563, allow for much better code maintainence. Other rules, like in C/C++ never using an int for any value other than 0-127, and never using a char for anything other than text characters, allow for code portability. These are just some of the rules. If your product is designed for one environment, you may have different coding standards. In the past, we have gotten together as a software team and reviewed other standards found online and combined the likes and the like-nots to create our own, tailored for our industry and requirements.
Style is good for readability and also for consistency. Requiring spaces before and after operators like = and + help in reading complex lines. Parens () help also. Setting requirements for function bracing (or what goes on a line, depending on the language), and tabbing help multiple programmers understand and easily see the program flow of others.
Anyone who protests that they like their own style better because they can read it eaiser (while everyone else can't) shouldn't be working for you. Team players are needed. We've resolved many such arguments satisfactorily in the past by simply putting it to a vote. And those team players gracefully accepted the majority.
So what if they are not all uniformly named? Has anybody actually seen a code base where it's possible to call a random function in a class without looking at documentation or the header file? As long as it's an informative name - and code reviews should flag bad ones - you should save your fight for something that actually matters.
Guidelines on naming, on the other hand, is a great idea. Clubbing smart developers over the head for this is pointless.
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.
One of the myths of software engineering, IMO, is that code is hard to read. For a competent programmer, code is *not* hard to read, in the sense that it's pretty easy to figure out what the code is doing. The problem is what the code is attempting to do, and possibly why. This is why brace styles, spaces versus tabs, and other "low level" coding standards do very little except to annoy. I've worked at several companies, each with different coding conventions, and I follow most of them. Unfortunately, I've found little relationship between maintainability and adherence to coding standards.
The best advice I ever got was to write "why", not "what" a piece of code does.
See? Completely useless. Let's try again:
Ah, much better! Any Computer Science peon knows that "counter++" increments counter. What they might not know is why. Those simple bits of "why" comments can make reading code so much easier.
Organizational comments (those that delineate what chunks of code inside of a method do) can be helpful, too. (Ex: "// Normalize string", "Encode string", "Send String") They make narrowing in on a particular "task" performed in a method even easier.
Other than that, however, the biggest and most persistent and most annoying problem I have is poorly-engineered code. Some people just do not know how to apply their college degrees. I wish CS degrees had a bigger emphasis in software engineering. Would you hire an architect who couldn't design anything bigger than a porta-potty? Why does the CS industry get away with doing the same thing?
I do like programming things that work super quickly, especially when they work super quickly, super quickly.