Forgot your password?
typodupeerror
Programming IT Technology

What Workplace Coding Practices Do You Use? 682

Posted by Cliff
from the software-development-is-more-than-just-writing-code dept.
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?"
This discussion has been archived. No new comments can be posted.

What Workplace Coding Practices Do You Use?

Comments Filter:
  • Comments (Score:5, Insightful)

    by Gyga (873992) on Wednesday November 16, 2005 @09:05PM (#14048789)
    Tell them to use comments in code, and be sure that they make them good comments.
    • Re:Comments (Score:5, Informative)

      by mopslik (688435) on Wednesday November 16, 2005 @09:08PM (#14048807)

      ...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 (Score:3, Insightful)

        by Threni (635302)
        > 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 (Score:5, Insightful)

        by republican gourd (879711) on Wednesday November 16, 2005 @09:31PM (#14048974)
        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 (Score:4, Interesting)

          by NemoX (630771) on Wednesday November 16, 2005 @09:42PM (#14049038)
          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.
          • Re:Comments (Score:3, Informative)

            by shinghei (594639)
            But the generated document is only as good as the comment itself, isn't it? Correct me if I am wrong, I don't think any of the tools that you mentioned can generate any intelligent comment. What good is the comment "The openSocket method throws a SocketException"?
      • Re:Comments lie (Score:3, Insightful)

        by rs79 (71822)
        " and finding out that those things no longer apply because somebody changed a 1 to a 2."

        Comments lie. Code never lies.

        • Re:Comments lie (Score:5, Informative)

          by Lehk228 (705449) on Wednesday November 16, 2005 @11:26PM (#14049498) Journal
          Comments lie. Code never lies.
          I beg to differ [acm.org]
          • Re:Comments lie (Score:3, Insightful)

            by bullgod (93002)
            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?

            • looong functions (Score:5, Informative)

              by namekuseijin (604504) on Thursday November 17, 2005 @02:03PM (#14054293)
              "I once came across a ~1400 line function"

              This is so fucking wrong and wicked the programmer who did it should go straight to hell. I'm sure there's no functional coesion in there: most likely there are many disparate tasks that should be each in its own function and called from there. I'm sure there is a lot of cut-n-paste in there that should be each in its own function and called from there.

              I'm sure you can guess where i'm willing to get to... more important than hungarian notation, comments or documentation in PDF format is abiding for these 2 simple rules: KISS -- keep it simple, stupid -- and DRY -- don't repeat yourself. Once you do it, coding and reading code is a lot easier.

              So, my advice:
              * Give meaningful names to important, global, business rules variables ( local variables like i or c are ok, since they are mostly irrelevant ) or functions/methods/procedures/subroutines
              * Write short, highly coesive functions/methods/procedures/subroutines
              * Stop the cut-n-paste madness! If you do it a lot, it's obvious the copied code if begging to be parametrized and be given a name. Programmers altering your original code will be thankful
              * Write modular code, not a plain, huge, stupid monolithic wall of letters. Even in languages with no namespace support ( C/PHP etc ) a good naming convention for functions of a certain module/header can do wonders...

              * and please: meaningful names don't mean phrase-like names like thisLocalVariableIsCool. Conciseness go a long way towards good readability...
        • Re:Comments lie (Score:3, Insightful)

          by mabinogi (74033)
          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.
    • Re:Comments (Score:5, Insightful)

      by joe_bruin (266648) on Wednesday November 16, 2005 @09:37PM (#14049012) Homepage Journal
      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 (Score:4, Interesting)

        by BobearQSI (786434) on Wednesday November 16, 2005 @10:28PM (#14049259)

        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.

        • Out of curiosity, what kind of platforms do you code for? Even my commodore 64 had 16-bit ints.
        • Re:Comments (Score:3, Insightful)

          by drxenos (573895)
          0-127??? Why? The standard guarantees that int is at least 16 bits.
        • Re:Comments (Score:3, Interesting)

          by Simonetta (207550)
          Anyone who protests that they like their own style better because they can read it easier (while everyone else can't) shouldn't be working for you.

          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 t
      • Re:Comments (Score:5, Insightful)

        by CausticPuppy (82139) on Wednesday November 16, 2005 @10:34PM (#14049288) Homepage
        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. [sourceforge.net] 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 (Score:4, Insightful)

          by Anonymous Coward on Wednesday November 16, 2005 @10:43PM (#14049332)
          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 (Score:4, Interesting)

          by GlassHeart (579618) on Wednesday November 16, 2005 @11:07PM (#14049427) Journal
          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.

          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:Comments (Score:4, Insightful)

        by Anonymous Coward on Wednesday November 16, 2005 @10:51PM (#14049370)
        I used to have that feeling about Hungarian too. Until i read Joel's view of how Hungarian is meant to be [joelonsoftware.com]. 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 (Score:3, Interesting)

      by Helios1182 (629010)
      If using Java, make sure they use Javadoc compatible comments for every class and method.
    • Pragmatic (Score:3, Informative)

      by dividius (693179)
      Read and apply the Pragmatic Programmer.
    • Re:Comments (Score:5, Interesting)

      by NilObject (522433) on Thursday November 17, 2005 @12:34AM (#14049827) Homepage

      The best advice I ever got was to write "why", not "what" a piece of code does.

      // Increment counter
      counter++;

      See? Completely useless. Let's try again:

      // We've processed one more message
      counter++;

      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?

    • Re:Comments (Score:4, Funny)

      by weicco (645927) on Thursday November 17, 2005 @03:42AM (#14050378)
      Oh yes, comments. Well we use comments as version/history information. We have every code file and project file on a single samba-shared volume. When somebody wants to change something he/she shouts "I'M OPENING THE FILE X, DON'T TOUCH IT NOW" and he/she has done modifications he/she adds very informative comment somewhere in the file (name/date/what was done), saves file back to disk and yells "OK, FILE X IS FREE NOW"

      Documents... There is no documents. Who needs those anyways? It's much more fun to code something when you really don't have any idea what its supposed to do.

      Test plans? Nah, waste of time I say!

      Testing? Well, somebody runs it and if it doesn't crash, it works.

      I must say I'm in the best damn work place ever! And now if you please, I'll go and find some ethernet cabel to strangle myself.
  • Joel on Software (Score:5, Informative)

    by Marxist Hacker 42 (638312) * <seebert42@gmail.com> on Wednesday November 16, 2005 @09:06PM (#14048793) Homepage Journal
    Has several excellent articles on the subject This [joelonsoftware.com] is about as good of a starting place as any.
    • by clockwise_music (594832) on Wednesday November 16, 2005 @09:27PM (#14048944) Homepage Journal
      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.
      • by RetroGeek (206522) on Wednesday November 16, 2005 @10:03PM (#14049144) Homepage
        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.
      • by NemoX (630771)
        Great post. Some additions...

        1. Use a code reviewer like FxCop for .NET stuff. You can build custom rules that your team decides on, and apply them to each program.

        2. Automate as much as possible with things like Ant or NAnt. The less people do, the less room for errors or discrepancies from project to project.

        3. Use something like Cruise Control .NET which will tie everything together, run coverage reports, automate builds, etc.

        4. Make a Utility library so that they have a common place to get repeta
      • 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:

        • CPU Efficiency
        • Memory/storage Efficiency
        • Maintainability
        • Portability
        • Correctness
        • Testability
        • Robustness
        • etc.

        ...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 s

    • Re:Joel on Software (Score:5, Interesting)

      by ajdavis (11891) on Wednesday November 16, 2005 @09:27PM (#14048945) Homepage
      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.
  • by FyRE666 (263011) * on Wednesday November 16, 2005 @09:06PM (#14048794) Homepage
    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.
  • by PIPBoy3000 (619296) on Wednesday November 16, 2005 @09:06PM (#14048796)
    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.
    • by ScentCone (795499) on Wednesday November 16, 2005 @09:45PM (#14049062)
      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.
  • by b0lt (729408) <b0lt@ls.qc.to> on Wednesday November 16, 2005 @09:07PM (#14048800)
    I like to think of it as "don't ask, don't tell" :D
  • by TheNarrator (200498) on Wednesday November 16, 2005 @09:08PM (#14048810)
    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.

  • by mekkab (133181) on Wednesday November 16, 2005 @09:09PM (#14048812) Homepage Journal
    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!
    • by Greyfox (87712)
      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

  • Looking for magic? (Score:5, Insightful)

    by YrWrstNtmr (564987) on Wednesday November 16, 2005 @09:09PM (#14048813)
    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.

  • A Good Coffee Break (Score:3, Interesting)

    by JoeShmoe950 (605274) <CrazyNorman@gmail.com> on Wednesday November 16, 2005 @09:09PM (#14048817) Homepage
    This doesn't directly answer the question, but a nice big break in the middle of the day helps me get myself on track easily. After a few hours of coding, I may start to slow down. If I just take an hour (eat lunch, walk around a little), my brain clears, and I come back fully productive. My work place allows this, and I'm not sure how many others do.
  • by Martin Blank (154261) on Wednesday November 16, 2005 @09:11PM (#14048837) Journal
    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).
  • by jellomizer (103300) * on Wednesday November 16, 2005 @09:12PM (#14048843)
    First language try to choose languages that work well on multiple platforms with at most a recompile. Languages like PHP, Python, Ruby, are Good. If you have to use .NET try to make your programs compatible with Mono. Even if you are using a Windows network and don't plan to switch anytime soon working with platform independent language give you the ability to better negotiate with MS for licensing price because your 3rd party apps will cheaply move over to the new platform. Also programs designed to be platform independent tend to migrate a lot easier to new versions of the OS. Avoid using and single platform library or other 3rd partly libraries unless you really need them. If they stop development you could be stuck.

    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.
  • by thepropain (851312) on Wednesday November 16, 2005 @09:14PM (#14048854) Homepage
    I'm all self-taught, so I have my own style which others tell me is impossible to make heads or tails of. The standard is: the boss promises stuff to our clients, and I have to whip it out [snicker] as fast as possible. Doesn't leave much time to make easy on those who would come after me. I jokingly call the mess of code I have to make JOB SECURITY.
  • Coding Practices (Score:5, Insightful)

    by Billosaur (927319) * <wgrother@HORSEop ... minus herbivore> on Wednesday November 16, 2005 @09:16PM (#14048863) Journal
    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.
  • Experience counts (Score:4, Insightful)

    by canuck57 (662392) on Wednesday November 16, 2005 @09:19PM (#14048886)

    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.

  • by blackcoot (124938) on Wednesday November 16, 2005 @09:20PM (#14048890)
    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.
    • 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

  • Standards (Score:4, Funny)

    by shoemakc (448730) on Wednesday November 16, 2005 @09:25PM (#14048929) Homepage
    Yeah, standards are great.....we've got lots of them :-)

    -Chris
  • Doxygen (Score:3, Informative)

    by segfault7375 (135849) on Wednesday November 16, 2005 @09:27PM (#14048946)
    One word.. doxygen [stack.nl]. I had been working on a program by myself for a few years and was really the only one who knew the guts of it. We got a new person on it so I could move on to other things, and rather than spending a week or two showing her what she needed to know, I spent a few days adding doxygen comments to the project, and she was able to read the generated documentation for herself and picked it up in no time. It plugs in to Visual Studio very nicely if you use that, and if not, you can easily write a batch file to update your documentation. I just can't say enough good things about this tool. If you can get your developers in the habit of documenting in the doxygen format, your documentation will basically write itself.

    Segfault
  • by MythoBeast (54294) on Wednesday November 16, 2005 @09:28PM (#14048949) Homepage Journal
    Ok, so the subject is misleading. As a C++ contractor with about 15 years of experience in a broad variety of shops, I've been exposed to quite a lot of different coding standards, from severely strict where they told me where and when I can use the spacebar, to the completely non-existent. Of all of them, I have found the GNU coding standards [gnu.org] to be the best balance between the flexible and the legible.

    A few other details that I'd like to add. K&R braces were invented, not by K&R but by the guys who typeset their book. It is a severe roadbump to try and read code where the braces are at the end of an if statement instead of vertically alligned.

    Try spinal alignment for variables. Most people align their variables like this:


    int something;
    void somethingelse;
    longobjectname theThirdThing;

    Those with more of a clue align them so that you can find the variable name easily in a mess of them:

    int something;
    void *somethingelse;
    longobjectname theThirdThing;

    This puts some major space in some cases between names and short type declarations. Try aligning them like this:

    ...........int..something;
    ..........void.*some thingElse;
    longobjectname..theThirdThing;



    The problem with this technique is that, if you ever post your code on Slashdot, you'll have to replace spaces with dots and spend fifteen minutes trying to get it to render correctly because SD doesn't support a simple PRE tag.

    Other tidbits that have helped. camelNotation rules. Don't use hungarian notation, it doesn't work in a severely object oriented enviornment. Instead, preceed your variables with a single letter that tells you where it's declared. l for local, m for member (of a class or struct), g for global, that kind of thing. I've seen "my" used for member and "the" used for static very effectively, also, but stick to one.

    Most of all, good luck. Remember that a lot of people's beliefs in this matter have no foundation except for what they've been doing for years. I have faith in my standards simply because I've seen what happens when you don't follow them, and that's mostly confusion.

  • Peer Review Often (Score:3, Insightful)

    by ear1grey (697747) on Wednesday November 16, 2005 @09:30PM (#14048968) Homepage

    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.

  • by Rocketboy (32971) on Wednesday November 16, 2005 @09:36PM (#14049001)
    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.

  • Standards (Score:3, Insightful)

    by umbrellasd (876984) on Wednesday November 16, 2005 @09:38PM (#14049015)
    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 (Score:5, Insightful)

    by eric.t.f.bat (102290) on Wednesday November 16, 2005 @09:45PM (#14049056)
    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.

  • by ralphbecket (225429) on Wednesday November 16, 2005 @09:45PM (#14049060)
    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
  • by Billly Gates (198444) on Wednesday November 16, 2005 @09:49PM (#14049082) Journal
    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
  • by pla (258480) on Wednesday November 16, 2005 @09:50PM (#14049083) Journal
    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.
  • by WiMoose (863260) on Wednesday November 16, 2005 @09:56PM (#14049115)
    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.
  • by cyberjessy (444290) on Wednesday November 16, 2005 @10:15PM (#14049202) Homepage
    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)
  • by dpbsmith (263124) on Wednesday November 16, 2005 @10:23PM (#14049233) Homepage
    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.
  • by oneiros27 (46144) on Wednesday November 16, 2005 @10:27PM (#14049251) Homepage
    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 [perl.com] article for perl.com (or his book [oreilly.com]) ... much of it applies to more languages than just Perl.
  • Doxygen (Score:3, Informative)

    by everphilski (877346) on Wednesday November 16, 2005 @10:30PM (#14049265) Journal
    In C++ we use Doxygen. Basically as you write comments inline you use a few shorthand markers (kinda like HTML tags, sorta, not really) to tell Doxygen what to pick up. Generates pretty good documentation and graphical class charts, etc. Works pretty slick, Doxygen is then pure HTML + png documentation of your code.

    -everphilski-
  • Coding standards (Score:3, Interesting)

    by El Cabri (13930) on Wednesday November 16, 2005 @10:34PM (#14049283) Journal
    Coding standards are language standard, or language specifications.
    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.
  • Code Complete (Score:3, Informative)

    by pigwin32 (614710) on Wednesday November 16, 2005 @10:51PM (#14049366)
    Steve McConnell's Code Complete [cc2e.com] is an excellent source for coding standards and a good read for any developer. I don't agree with everything in the book but it is comprehensive. Ignore that it's published by Microsoft Press, it's a good one.
  • Some of my rules (Score:3, Insightful)

    by gregm (61553) on Thursday November 17, 2005 @12:55AM (#14049907)
    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
  • by RKBA (622932) * on Thursday November 17, 2005 @01:23AM (#14050005)
    I wouldn't work for any company that tried to tell me what "coding style" to use. I'm a retired programmer with 35+ years of experience BTW.
  • Domain Driven Design (Score:3, Informative)

    by Symbiot (815778) on Thursday November 17, 2005 @02:00AM (#14050108)
    If you want code that can be readily understood you need something other than coding conventions. Coding conventions only make the code all look the same. You can get almost all of the benefit (without most of the arguments) by saying only that each file must be written with the same coding convention throughout. The code will get prettier and prettier with tighter conventions and developers will waste less time reformatting each others code. But it won't do a thing to make your project more understandable.

    For that you need an understandable design and the best advice I've ever seen for that is in Eric Evens' "Domain Driven Design" http://domaindrivendesign.org/ [domaindrivendesign.org]. The advice there will work for both Agile and non-Agile projects and its core themes are pretty much unavoidable truths about how to write code for a project that is also written about the project: use language that comes from the projects domain, insulate code from each domain or sub-domain from the rest of the world, keep each method at the same level of abstraction (that's big) and make implicit concepts explicit, to name a few. The key is for your developers to consider themselves to be authors and to strive to keep each little piece of code they write on-topic. Not only will it be easier for new developers to come up to speed but the code will work a heck of a lot better too.
  • by Todd Knarr (15451) on Thursday November 17, 2005 @03:42AM (#14050377) Homepage

    As someone with 20+ years of professional programming under my belt, a lot of it doing maintenance and enhancement of existing code, I'll say this: most of what's considered "coding standards" doesn't much matter. Indentation, brace positioning, type prefixes on variables, underlines vs. StudlyCaps, capitalization in general, most competent programmers can pick up on any variation quickly. The few things that count are more general:

    1. Comment logic and motivation, not the code itself. I can figure out what the code's doing. What I need coming into it's what it's supposed to be doing, why the code does things the way it does, what the data structures are supposed to represent and how they're supposed to be used. On routines, tell me what the routine's supposed to accomplish, what arguments it takes in and what results it spits out (including error conditions).
    2. Make variable names descriptive. Abbreviate where it makes sense, but make the name give me an idea of what it's for. It's less important that I know it's a string than that I know it's the last name of the customer whose order you're processing. And if all it's for is the index in a loop and it's got no meaning outside of the loop, then yes i and j are perfectly legitimate names that any programmer will (or should, at least) recognize.
    3. Programmers should try to use consistent indentation, brace alignment and other formatting things when writing new code, and should try to match the existing formatting when modifying code. Emacs and other modern editors can do automatic indentation and pretty-printing for you, make use of those features and make it easy for programmers to set their editors up to match commonly-used styles. And make them clean up garbage, things like trailing whitespace and irregular alignment are disproportionate pains. I don't care much what the tab interval is, but I hate it when the interval changes every few lines.
    4. Use whitespace for readability. Code like if(strlen(obj.getname())" is legal, but it's a lot harder to read than "if ( strlen( obj.getname() ) ". It also makes it easier to distinguish functions ("f(x)") from control structures ("if ( x )"). Similarly, putting the opening brace of a loop or conditional on the end of the line may be compact, but it makes it hard to distinguish the start of a multi-line body from a single-line body followed by some lines with the wrong indentation.
    5. A few small formatting things are overall useful. Symbolic constants should be immediately recognizable as such and all-caps is a commonly-recognized way of doing that, for example. And the indentation level of the code should match the logical level, that is the "then" and "else" bodies of an if statement should be indented further than the "if" and "else" keywords (which should both be indented at the same level).
  • by crucini (98210) on Thursday November 17, 2005 @04:20AM (#14050509)
    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.
  • by KZigurs (638781) on Thursday November 17, 2005 @08:28AM (#14051138)
    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! :)

3500 Calories = 1 Food Pound

Working...