What Workplace Coding Practices Do You Use? 682
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?"
Help people play to their strengths etc.... (Score:5, Interesting)
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.
A Good Coffee Break (Score:3, Interesting)
Doesn't matter (Score:1, Interesting)
Works for some companies not others. (Score:3, Interesting)
Second have a Good Data Warehouse try to use Rational Database servers that support Stored Procedures and Triggers, which is dependable. MySQL 5, PostGreSQL, MSSQL, Oracle are all good choices. I would put money to give all the DataBase Servers some good specs and conversly I would put all the data manipulation into Stored Procedures and Stored Functions. Also when creating them give them a prefix to show that they are your companies specialized functions and not built in the Database Server. The Database should give you the data they way that is most convenient for you to use. The reasoning for this is that it normally reduce network traffic to the SQL Server, and allow porting applications to different languages and platforms easier because the data format part is still complete.
Third use have all your apps on your intranet be web based. first it eases deployment and also allows desktops to be upgraded without killing the app every security patch.
So if you make a all your Apps Web Based with the bulk of the calculations on the Database server and having the Web Language handle the User Interface, and depending on you size of you apps a 3 or 4th tear with custom libraries for standardized uses of Interface and data a.
Re:Joel on Software (Score:5, Interesting)
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.
Re:Comments (Score:4, Interesting)
Re:Evolutionary Prototyping (Score:4, Interesting)
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.
Re:Programming Standards (Score:4, Interesting)
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.
Re:Programming Standards (Score:3, Interesting)
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.
Ideal workplace (Score:2, Interesting)
Beanbags. Very useful. Especially when you've got those incredibly stubborn bugs, and feeling careless and jumping about and falling. *grin*
Food and drinks (coffee). Increases productivity greatly.
I've also appreciated how the QA team is ideally located in separate offices from devel. Things get pretty messy.
Re:Comments (Score:3, Interesting)
Re:Never comment! (Score:2, Interesting)
umm, it sounds to me like you are one of legions of 'application level' programmers. the separation of an application into 'tiers' (which have no real formal definition) just obscures data contraints into a maze of levels of code. Totally unnecessary...the closer your constraints are to the actual data the cleaner and more maintainalbe your application will be.
Very few applications need to be portable across databases. If you pick a good database (PostgreSQL), there is little reason to port. Application languages (ruby, c++, COBOL, Java, etc etc etc) are a dime a dozen and will be switched and/or mixed a dozen times over the lifetime of a enterprise app.
Re:Comments (Score:4, Interesting)
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.
Coding standards (Score:3, Interesting)
A developer who does not understand any piece of code does not understand the language and hence is incompetent.
Of course one can write obfuscated code, and developers should be encouraged not to. If your developers are not capable of writing meaningful code in a language, change the language, change the developers, or as a last resort change careers, your company stinks.
Setting coding standards would be the same as restricting the English language to a subset in which, for example, George W Bush would be capable of forming a meaningful and consistent sentence.
Re:That's Like Scrum... (Score:1, Interesting)
> But our 30 person team is kicking the ass of my old 8 person team in terms of consistency and quality. And its all because of this one guy.
WTH? A 30 person team SHOULD kick the ass of an 8 person team. Worst case: You have 8 guys coding and 22 guys doing nothing. If one person is responsible for making a 30 man team better than an 8 man team, then they should fire the other 29 of you guys and let him work in peace. Hah. Either that or maybe he's tricked you into thinking you're actually doing work, but instead he just has you staying out of his way.
I didn't really intend for this to be a personal attack when I started it, but it sure seems to have turned into one. Sorry about that. For all I know, you're just as productive as that guy. Maybe you ARE that guy.
The original point was that you'd have to be horribly mismanaged to for a 30 person team to do worse than an 8 person team. Maybe you meant 80?
Re:Comments (Score:4, Interesting)
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.
Re:Programming Standards (Score:3, Interesting)
Something else I've found useful (which I think I got from a McConnell or Maguire book) is the idea of priorities in your coding, which should be part of your coding standards. That is, take a set of features/aspects of code like this:
...and then put them in order of priority for each project you work on. The order will vary depending on the project, but a lot of coders will program with the same priority list in mind no matter what they are working on (e.g. obsessing about efficiency above all else) unless you actually tell them what the priorities should be.
Making the list and putting it in order just puts it on everyone's radar. I have at times had the list taped to the edge of my screen, so when I come up against a design decision, I check the list for guidance.
Re:Programming Standards (Score:2, Interesting)
In 30+ years of coding, I've used many different "standards". I've come to the realization that the details of the standard are unimportant -- what's important is that you have one.
Personally, I find "hungarian" variable names painful to behold. But if I'm working on code that used them originally, I'll try to make myself be consistent with the existing style.
Indenting and white space standards are totally unimportant with a good IDE. In Eclipse, hit control-shift-f to make it look the way you want it to.
Commenting is more problematic. I've gone from heavily commented to no-comment XP programming. I've settled down into a "minimal comment" regime. I try to write code that doesn't need comments by using short functions with meaningful variable, method, and class names. But where a comment can inject additional clarity, or where the code is necessarily obscure, then a comment can really help. (And by obscure, I don't mean "obfusticated" -- I mean code that is handling some bizarre real-world circumstance that most code readers probably would not think of.) Use your judgement. Ask yourself "if I came back to this code in a year, what bits would I be confused about." Then clarify that code. If it can't be further clarified, write a comment.
As for "javadoc" or "pod", I think that it is essential if you're writing code that will be used in "binary" form by others. Try using something like DOM or Spring without documentation and see how far you get! But Javadoc for the sake of meeting some metric ("all public methods must have Javadoc") is purely silly. Even when I was working on a strict XP team that enforced a "no comments" discipline, we put Javadoc on a couple of methods. We found ourselves continually going back to read the code to answer questions such as "is this index 0-based or 1-based?" A simple Javadoc comment stating "index is 1-based" saved many minutes of coding time.
Practice test-first writing. It's weird the first several times you do it, but at least for me, the more I do it, the more comfortable it feels. You can't always do it, I'll be the first to admit. But if I never write a line of code that doesn't have a test motivating it, I have a lot more confidence that the resulting code is going to do what I intend it to do. On the flip side, if I can't think of a test case that requires some particular "if branch", then maybe I don't really need to write that line of code.
Get a coverage tool and use it. Don't blindly try for ~100% coverage (you'll never get it anyway), but it can point out bits of code that are undertested.
In addition to "writing specs for new developers", pair a new developer with an experienced developer for a few weeks. Just a couple of hours a day will transfer the group practices much faster than any document will. IMO, this works best when the experienced developer is the "navigator" and the new developer has his or her hands on the keyboard, "driving." Doing == Learning. Watching == Boredom and Distraction. As an experienced developer, this is really hard for me -- I want to drive -- but it really does work.
Practice group ownership of code. Don't let any individual piece of code belong to a single person -- in the sense that only one person understands it and only one person is "allowed" to touch it. Not only can this save you when the "guru" leaves, but it helps to prevent wheel-reinvention and accretion of "ugly code". It encourages the attitude of "if it's broken, and I'm working on it now, then it's my responsibility to fix it."
Frequent integration in a multi-developer shop is essential. Don't let each developer work alone for a month or maybe even a week without reintegrating the code.
A bunch of this sounds very XP-ish. That's because XP is not a new thing. XP is a combination of good practices all "turned up to 11." We tried XP for about a year and had mixed results -- out of 4 projects, one was successful, one was an utter and complete failure, one was mothballed
Least worry (Score:1, Interesting)
Unless you have procedures in place for testing, deployment, version control, code sharing, change request system and more, then those are bigger concerns than how you indent your code and what naming conventions to use.
I'm not saying that coding practices aren't good. Just that you likely will achieve better productivity by focusing on other things.
If you are hiring, make sure that you hire a seasoned software engineer and not a code monkey next time. If you aren't hiring, then research the web for ways to improve how your team builds software. What is best for you will differ quite a bit depending on your exact situation.
If you want code practices, then focus on "best practices" or patterns over cosmetic rules. Try to centralize code that support common patterns, such as error handling, database access, GUI components and so on.
Think about it this way. Your team can only absorb a certain amount of improvements. How much this is depends on the individuals on your team and how well you are able to introduce these new things. Think about the improvements that you want to make and prioritize them.
Man, this ended up sounding like I think I'm the best thing since sliced bread. I'll post anon.
Re:Question about Hungarian Notation (Score:3, Interesting)
the problem is not when you look at intPositionSensorReading but rather when it has been changed to a decimal, or when you need to change it to a decimal suddenly you are either wasting time editing every piece of code using that variable. or you cause incorrect comments to be all over the code.
IFF VB would enforce and automate hungarian notation as an option it would be useful (i use VB as the example because it is the only place i have run into Hungarian Notaiton)
More HERE [ootips.org]
Watch Your Cornhole (Score:2, Interesting)
If you can, put together a process that specifies how all of you can define a product, start a project (get a suit to sign off on it too), deal with changes in requirements without tanking the project, assure quality, and ship. The code will take care of itself because it is the only thing you will have a decent amount of control over. Everything else is cross-functional, which adds a great deal of difficulty -- hence the need for policy.
Just remember the "ship" part. Don't get stuck too long in defining a process because none exist which are universally indicated, completely effective, or free from ruinous meddling and circumvention. Worry more about what can keep you from shipping and try to set a policy that will prevent those things.
And most of all, watch your cornhole -- technical leads are sh*t magnets.
Re:Comments (Score:3, Interesting)
Maybe instead these people can be requested to write programs that reformat the written code from their style to the company standard style. They should do this, of course, on their own time at home.
No magic numbers in the code is a good idea. Especially for embedded systems code where there are lots of configuration registers in the microcontrollers to set up.
For example, avoid constructions like:
ldi config, 0x28 ; LoaD Immediate Value into register
instead use:
ldi config, (1 bit5goodname) | (1 bit3goodname)
I'm always encouraging people on embedded coding sites to do this.
Running the comments through a spell checker is a good idea. If you can get the language environment to separate the comments from the active code and feed the comments alone into a good spell checker. I haven't seen any compiler yet that does this, but it should be too hard to set up a text filter program for it. A least no one in your company will be embarrassed by simple misspelled words in the comments. Great for your H1-B people also who are using English as a second or third language and haven't mastered the unusual spelling of thousands of common English words.
I'm also becoming a strong believer in Talking Documentation. Get a high quality Speech-To-Text converter program and a fast PC. Place this PC next to the development PC with the source code. Start the Sp-to-Tx and the source code listing. Describe in words the entire listing as if there were someone there who was endlessly fascinated by the code and you. Take hours if you need too. Save the text file of the transcribed dictated documentation with the source. Don't be concerned about formatting and paragraphs or even coherence. If needed, someone can do all that later. It's important just to have the detailed dictation text that describes the source. It seems strange, but it does work as a documentation technique.
Don't forget to spell check your own stuff too.
Re:Comments (Score:5, Interesting)
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?
Good way to get rid of your best staff... (Score:3, Interesting)
Re:Comments (Score:4, Interesting)
C++ coding style (Score:2, Interesting)
The only time I've had a memory leak in the last 10 years was when I had to break this coding standard (eg for library compatibility).
The second most important coding style is to use pointers only when necessary - some graph algorithms need them, and so do some "legacy" C libraries. Otherwise, use references - there in the language for that purpose.
The 3rd most important coding style is use standard library container syntax whereever it makes sense. Even if you write your own container libraries - follow standard library conventions. Makes it much easier for other coders to follow.
After this follow a bunch of useful stuff - eg ensure that meaningful default, copy constructors and assignments are available for your class, use the const keyword wherever it makes sense
On the subject of naming conventions - naming conventions can lie! Tools like doxygen will quickly tell you what a particular indentifier refers to in a particular context. If not, then grep is pretty handy at working it out. However, often one wants to use the same name for type names and instance names - a convention like first letter upper case for typenames, or appended _t can help the addled brain.
Throw open a question now - any good tips for organising namespace names, and macro names to avoid the inevitable clashes?
Be picky about what you cover (Score:2, Interesting)
1) First, there are arbitrary choices where uniformity across the company is more important than having a perfect fit for each project.
A perfect example is the choice of information management tools and formats. Unlike an indentation style, a source control or bug database learning curve can be a significant barrier to a developer helping out another team for a few days. It's also important to ease access for non-development personnel. Pick some tools and make everyone use them.
"Every project shall use Subversion as its source control system, BugZilla as its bug tracking system, and DocBook for user documentation."
Depending on the size of your company, the choice of a unit test framework or a build tool might be standardized. Keep in mind the benefit of diversity in these matters, though.
2) Second, there are matters of practice that can be fairly unambiguously stated and checked.
A few examples:
"Every project shall version its acceptance tests."
"Every project shall archive acceptance tests and test results for every software release."
"Every project shall publish a current schedule, updated daily, and a summary of outstanding defects, updated at least weekly, to the IT intranet."
"Every project shall maintain a system of peer review, so that all code must pass by a second pair of eyes within a week of being committed."
"Every project shall automatically generate API documentation."
3) Third, there are matters that may be important but shouldn't be included in your standards.
There are two good reasons for being so picky. First, you want your standards to be as short as possible so people actually read them. Second, you don't want to publish standards that you can't or shouldn't enforce.
An example of a good coding rule that doesn't fall into the first two categories is "Document intent, not mechanics." Everyone should do it, but checking and enforcement should be done among project teammates, not by a higher level of management.
Another example is "Test everything that can break." The extent of test coverage can only be determined by people actually working on the project, so you can't enforce this rule. It's a great rule, but it doesn't belong in your standards.
Since so much attention has been paid in other posts to matters of code formatting, I might as well add my two cents. For languages where there is One True Way, such as Java and Python, there's no good reason to deviate from the One True Way. Is it really your job to point out and enforce the obvious? I don't think so. Let the project managers handle it.
For other languages, such as C++, there are a variety of accepted styles. Uniformity is good, and every project should certainly pick a style and use it consistently. Whether to pick a uniform style for the company is a judgment call. Professional C++ programmers are used to dealing with variety and shouldn't have problems switching when they jump from project to project. For your company the right rule for dealing with C++ projects may be this:
"Every project that uses C++ shall adopt and publish a uniform brace and indentation style."
Or it may be this:
"All C++ code shall be formatted as in The C++ Programming Language, Special Edition."
A final note: Be firm about setting standards, but talk to people first and don't issue any orders that you don't have the muscle to enforce. Find out what people's prejudices are and eagerly defer to them when it doesn't make much difference. Migrating CVS users to Subversion should be no big deal, but if a bunch of stubborn CVS users refuse to migrate, and you fail to make them, all the rest of your standards will go out the window as well. If your authority is shaky, the best way to shore it up is to avoid controversy and issue a bunch of commands that nobody minds obeying
Do you think coding standards will help? (Score:2, Interesting)
Readable code is a prerequisite for understandable code, education is a prerequisite for understanding.
Coding-standards is trying to apply a method of syntax to an education-problem, it's not gonna work. Don't think that coding-standards will give you readability, much less understanding.
My advice is to get a few people with experience, solid, broad knowledge of the language and a pragmatic attitude to sit down and pair-program with the people who write hard-to-understand code and those who have a hard time understanding code that should have been easy to understand.
Let people present idioms, discuss patterns and create a place where "readability" is a code-quality and a goal. (BTW: Don't fall into the "everthing is a pattern"-trap) This is not a coding standard, it's an education of "this-way-works-well-for-this-and-that".
Promote knowledge of the language standard-library, instead of duplicating it yourself. Learn to shun "wrappers". Use the language-features for what they were meant to do, not for insert-really-cunning-hack-here. Model things as they are, instead of cutting coreners or adding complexity.
Check out c2.com http://c2.com/cgi/wiki?WelcomeVisitors [c2.com] it's really a place worth knowing. Read the dialogs, they may not all be truly insightfull but they provide you with excellent examples of what people think about in development and why it's not that easy to do-the-right-thing.
One specific thing i've found is that most people write code by copying (atleast a skeleton) from somewhere else. Accept this, and to give them something *proper* to copy from, short, complete programs -- taken from real situations, Not crappy code-project articles where people try to show off how complicated a technique they can master.
Re:Comments (Score:3, Interesting)
And how can the result of this rule be that developers use tabs?