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

[Gyga (873992)]

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

Re:Comments

[mopslik (688435)]

...be sure that they make them good comments.

And make sure they update comments if changes necessitate it. There's nothing worse than reading through a function's description, complete with well-documented inputs/outputs/conditions/etc. and finding out that those things no longer apply because somebody changed a 1 to a 2.

Re:Comments

[republican gourd (879711)]

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

[joe_bruin (266648)]

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

[Py to the Wiz (905662)]

"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

[jomegat (706411)]

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

[dorkygeek (898295)]

For example:

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. If it is, then the code within is executed

-this is a good, easy to understand comment.

Is this supposed to be a joke??! Both of them are worst comments, because they only formulate in english what the code already says by itself. Everyone can see that this is an if-statement, everyone is able to identify the condition, and everyone knows the semantics of an if-statement.

A good comment is not describing what is done (since everybody can see that from the code itself), a good comment describes why something is done, or what the overall objective of the statement is.

For example:

if (x == 456) { // Check if step motor reached final position. If yes, halt motor, otherwise step forward.

This is ways more useful. Even more useful would be to already use self-describing symbol names in the code itself, like

if (currentPosition == finalPosition) { ...

Re:Comments

[naibas (109074)]

Both of them are worst comments, because they only formulate in english what the code already says by itself. Everyone can see that this is an if-statement, everyone is able to identify the condition, and everyone knows the semantics of an if-statement.

A good comment is not describing what is done (since everybody can see that from the code itself), a good comment describes why something is done, or what the overall objective of the statement is.

Amen to that.

In addition to the original comments being redundant, there's also the issue of the code and the comments getting out of sync...

The company I work for just wrote up a formal coding standard, which includes everything from a guide to our internal hungarian notation, indentation guidelines, and even which C++ features/paradigms are supported, frowned upon, or not allowed. All the coders got a chance to send in feedback before it was finalized, and we even ended up with a list of recommended reading on the subject, including:

• Sutter & Alexandrescu's C++ Coding Standards,
• Meyer's Effective C++,
• Meyer's More Effective C++, and
• McConnell's Code Complete.

The idea is to keep the code readable and maintainable with the least amount of re-invention of the wheel. With good coding practices, it's easier to avoid bugs in your own code and spot them in others (reviews are also a big plus on both counts). And it gets any religious battles out of the way up front, so you don't have to waste time bickering later on.

Re:Comments

[Webmoth (75878)]

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

[iabervon (1971)]

I prefer:

if x==456 then //checks to see if x is equal to 256. If it is, then the code within is executed

That way, there's less chance for confusion if the code gets modified in the future.

Joel on Software

[Marxist Hacker 42 (638312)]

Has several excellent articles on the subject This [joelonsoftware.com] is about as good of a starting place as any.

Programming Standards

[clockwise_music (594832)]

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.

Re:Joel on Software

[ajdavis (11891)]

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.

Help people play to their strengths etc....

[FyRE666 (263011)]

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.

Evolutionary Prototyping

[PIPBoy3000 (619296)]

In my job as a web developer in a healthcare system, I'm all about evolutionary prototyping and other interative [wikipedia.org] 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.

GOOD code review; Chief Designer at every inspecti

[mekkab (133181)]

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 (564987)]

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.

Coding Practices

[Billosaur (927319)]

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.

code complete has some good things to say

[blackcoot (124938)]

on this particular subject. i believe code complete 2 came out "reasonably recently". that said, were this my task, i'd say the following:

1) document things thoroughly using a tool like doxygen. there is no excuse for interfaces not to be thoroughly documented
2) adopt a standard naming convention. in java, this is easy -- just use the default. in other languages, you'll probably have to make your own up.
3) pick an indentation style. it really doesn't matter which since tools like indent can convert between them almost painlessly. all code that goes into the repository is run through indent to put it into a standard format
4) require that code compile cleanly with no warnings at the most anal retentive compiler settings before it can be checked in unless there are good reasons to ignore the compiler warnings
5) average devs are only able to commit to the "head" fork (or equivalent in your sccs). the code is not committed to the "real" fork until it passes whatever tests you have
6) incorporate tools like valgrind into your testing cycle --- they should come back largely clean. if they don't, things need to be fixed unless there's a really good reason not to.
7) people who check in code which breaks cvs or, upon a code review, are found to not sufficiently adhere to your guidelines owe their dev group donuts.

Worry about what not to do, too

[Rocketboy (32971)]

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.

Geek minds

[eric.t.f.bat (102290)]

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.

Never comment!

[Billly Gates (198444)]

Its for wussies!

-USe tons and tons of goto statements.

-Make sure you use particular letters capped for variables of different types to make them more confusing for the losers who can't read the code and remember what each one was.

- always make calls by reference using pointers as arguments. Don't use call by values.

- Hell user other pointers that use other pointers to make things more interesting. Reassign them all over the place

- Never use a three tier model when developing client/server apps. This only creates redundancy and gets in the way of solving the problem.

- When linking to a database always use vendor specific extensions and avoid a database layer using something like odbc. It makes use of the advanced feature set by the particular RDBMS.

- Be a man! Show how much you know perl. Alot of one linners can save tons of time with exotic line switches

Oh last... make tons of money and gain job security because no one in Earth will be able to understand or work on your projects after doing all of these things. Enjoy

Ahahahahaaa... heh... Snrrrrrkkk. Kidding, right?

[pla (258480)]

without wasting a couple hours just to figure out the code.

A couple hours???

Look, no offense, but you either only deal in "toy" code, or you have such high expectation that you will fail, and quite spectacularly.

A new coder, even an experienced one, takes days or even weeks after coming into an existing project before he can contribute anything but the most trivial of changes. For a truly massive project, or one that requires intimate domain-specific knowledge in a niche industry, extend that to months.

If you can find a way to get an unfamiliar newcomer up to speed on any "real" project in a matter of hours, consider your talents wasted in your current position.

Fundamental coding truths

[WiMoose (863260)]

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.

For .Net, here is what we use

[cyberjessy (444290)]

C# - The C# Coding Style Guide [icsharpcode.net], Mike Krueger(SharpDevelop). This is probably the most widely used one (Novell). It largely agrees with Microsoft's internal coding standards, with a few exceptions.
    VB - .Net Coding Standards, part of the SDK. This is not comprehensive though, like the C# doc mentioned above.

Version Control -
    Server: Subversion + Apache
    Client: Tortoise SVN (Excellent) [We also use Perforce, CVS, VSS(Commercial apps)]
Continuous Integration - Cruise Control.Net
Intranet, Knowledge Management - DotNetNuke (www.dotnetnuke.com)
Project Management - dotProject (PHP) (www.dotproject.com), MS Project
Unit Testing - NUnit (www.nunit.org)