Fog Creek Software
Discussion Board




Coding Standards

I thought 'coding standards' were dead.  Seems stupid to me, in this day and age, wasting people's time by forcing them to conform to goofy Hungarian variable naming conventions.  I'm not talking about good software engineering practices - I'm talking about, 'There have to be three spaces in you tabs, and you can't use a tab character, and there has to be a sixteen letter prefix recipe to let you know the variable's data type, and there must be a line of asterisks between functions, etc.'  There are editors now that color local variables a different color, and you can hover the mouse over a variable to see its data type, (no need for Hungarian).  The editor automatically inserts lines between functions.  If you want to see who made a particular change, you don't need this in the source code:
 
  "// JDB - 08/17/2003 - I fixed the whosis and the whatsis". 

Use a darn version control system!  It's a new century - can you please get with the program?  Aren't we old enough now to code in our own styles as long as we're consistent, and follow good engineering practices, mom?

anon
Tuesday, July 13, 2004

consistent coding standards help to ease code reading, despite all those nifty bells and whistles in your IDE.  Telling the types of variables and who made a change aren't the only considerations.

It's common knowlege that it's MUCH easier to write code than to read it.  Coding Standards go a long way toward evening that imbalance.

Although I'll admit that when I do not agree with the coding standards in a given shop, it impacts on my productivity because it's counterintuitive to code that way.  You either learn to deal with it or work elsewhere.

Of course, a third option is to ignore the coding standards, but that may impact your survivability, and will certainly impact your relationships with other developers on the team.

muppet from madebymonkeys.net
Tuesday, July 13, 2004

Ever try and read a long post in these forums where there are no paragraph breaks?  It's extremely difficult to do; generally I just give up.  Syntactically, it's all correct -- punctuation is all correct.  It's just the spacing that's wrong.

Coding standards are just the same.  It's much easier to read when everyone spacing things out the same and the braces are in the correct places.

Almost Anonymous
Tuesday, July 13, 2004

+++the braces are in the correct places. +++

of course you know that this is subjective.  ;)

muppet from madebymonkeys.net
Tuesday, July 13, 2004

>Aren't we old enough now to code in our own styles as long as we're consistent, and follow good engineering practices, mom?

Yes, dear, until I have to maintain your code 3 years after you've left the company and waste precious time figuring out your "style" in order to do my job.

Standards should be agreed upon by the development group as a whole (not imposed from above by management). I don't care where my curly braces go or how to name my variables, as long as we all use the same style.

We should leave the "rugged individualism" for our personal projects.

Michael Ealem
Tuesday, July 13, 2004



You speak about many things that exist purely in the functionality of the IDE's that you're using.

That works fine as long as you always have your trusty IDE available and that functionality always exists in it.  Unfortunately, this may not always be the case.


I personally encourage people to use descriptive variable names, indenting standards are nice, especially when if/then/else, loops, or other choices are involved.

There are many formating tools (jalopy comes to mind) which will catch and resolve many of these things automagically.

KC
Tuesday, July 13, 2004

Ok, so can somebody tell me why this old guy in our office who happens to be the most senior and sets the coding standards, insists all methods my have a commented section like:

// [3 spaces] @param: int NumRecords    Number of records
// [blankline]
// [3 spaces] @return: void

void CClass:DoThing(int NumRecords)

And if you forget these (all code has to go to him before being checked in, you have to copy it to a certain folder, then he'll copy it to an "out" folder after he's done reviewing it), he'll pull you into the office and lecture you on the proper format.

I'm too embarassed to ask him what's up with the @'s and the 3 spaces. I mean...wtf?

Gen Y
Tuesday, July 13, 2004

And can somebody tell me why old guys like Joel would create message board software without a "preview" button? I mean, just a 'post' is sooooo 1995. 

"my" in my post should be "must".

Gen Y
Tuesday, July 13, 2004

Gen Y -

I'm not sure where that comes from either, but I've seen that style used here, and it annoys me.  I understand wanting to document the input/output of a function in a standard way, but the spaces and the @'s are nonsensical to me.  Perhaps they're cues for some sort of auto-documenting app?

muppet from madebymonkeys.net
Tuesday, July 13, 2004

+++the braces are in the correct places. +++
"of course you know that this is subjective.  ;)"

But the brace-style can be correct to the coding standard -- whatever is it.  It's better for *all* the braces to be subjectively "wrong" than for the developers to use different styles throughout!

Almost Anonymous
Tuesday, July 13, 2004

Automatic documentation generator, similar to JavaDoc maybe ?

WhatTimeIsItEccles
Tuesday, July 13, 2004

That's why I love eclipse.  We all reformat our code based on our own templates, and the structural compare still allows us to track changes.

Brian
Tuesday, July 13, 2004

Gen Y,

I can see where the OF is coming from.

The only problem I have is why on earth is he checking it manually.

Why hasn't he written a parser that automatically generates documentation based on the standard?

Ged Byrne
Tuesday, July 13, 2004

Coding standards work on two levels: the first level deals with ergonomic things like tab lengths and where to put the curly braces, and the second deals with actual code.

On the ergonomic level, I can see the benefit of having all code in a project look the same, but I also appreciate how hard it can be to switch back and forth between C- and Java-style curly brace philosophies.

On the code level, it is usually amazing how a few well-chosen standards can drive up code quality. Using a simple scheme for variable names is useful. I don't think Hungarian notation is a good idea (you should know the types of your variables because of a nearly declaration, changing a type requires changing all the variable names!). Mandating that the code compile with zero warnings is useful. Mandating the regular use of a Lint-like tool is useful. Mandating that code be exercised to achieve x% coverage is useful. Mandating how memory is managed is useful. These codinmg standards are useful.

C Rose
Tuesday, July 13, 2004

"@'s are nonsensical to me.  Perhaps they're cues for some sort of auto-documenting app?"

Whoa..  a PHP and Java programmer who doesn't know about PHPDoc and JavaDoc?!?  *grin*

That's the standard for autodocumentors and normally looks somethig like this:

/**
* This sentence is the short description.
*
* Longer description is optional and
* goes here and  generally rambles on
* for a few lines.
*
* @param  Description of param one
* @param  Description of param two
* @returns Description of return value
* @see OtherMethod()
*/
ReturnType methodName(Int param1, Int param2)

The block comment with the two asterisks starts the doc-comment (as they are called) and @-whatever are keywords to the documentator.  When this is generated the descriptions are mixed with type information from the actual declaration to produce sweet documentation.

In PHP, because it's typeless, you put the types are the param lines as well and the get included into the documentation.  This type of documentation is very important in PHP because it's important to know what types you can pass in:

* @param  integer    description of param1

Almost Anonymous
Tuesday, July 13, 2004

The fault is not in the coding standards, if you don't know about JavaDoc or phpDoc staring at @ signs isn't going to enlighten you (though I guess you could have researched it); the fault lies in it not being explained to you why its done as well as what is done.

The Why always explains the What, unless it involves the word Because on its own.

Simon Lucy
Tuesday, July 13, 2004

I've yet to encounter PHPDoc and JavaDoc.  No shop I've ever worked for bothers much with documentation (I know, I know) and for my home projects, my documentation is my code (I know, I know).

I guess I should look into both, may save me some headaches.  (UNDERSTATEMENT WARNING)

muppet from madebymonkeys.net
Tuesday, July 13, 2004

>>"Aren't we old enough now to code in our own styles as long as we're consistent, and follow good engineering practices, mom?"

And while we're at it, why don't we get rid of all those stupid traffic laws.  After all, *EVERYONE KNOWS* that it's bad to drive too fast.

Rammalamma Dingdong
Tuesday, July 13, 2004

You must not look at much 3rd party Java or PHP code...  it's pretty much all Javadoc'd. 

For whatever reason (probably the lack of type-safety) I always doc my personal PHP code.  My C++ doesn't get it -- it's just I don't have much to say!

Most comments are really just stupid...  example:

/**
* This method does such and such
*
* @param  Number of seconds to delay
* @param  Number of iterations
*/
void suchAndSuch(Int delaySeconds, Int iterations)

That's a massively useless comment block but unbelievably common.

Almost Anonymous
Tuesday, July 13, 2004

Don't get me started on type safety and why I think it's useless :)

You're right, I don't spend much time on 3rd party PHP or Java code.  I've attempted in the past few months to find a decent PHP CMS, because mine was taking too long to develop, and summarily decided that everything available on the internet from other developers is crap.  :)

Although, I did come across that style of comment block.  I didn't know it was for PHPDoc, though.

muppet from madebymonkeys.net
Tuesday, July 13, 2004

"The only problem I have is why on earth is he checking it manually."

Ged -- he has to check and approve all general coding to make sure it doesn't "break" his precious, legacy codebase he was the architect for about ten years back. Then he sends back "ok" or "fix this" in a standard email form with some 20 different fields. If code resubmission is required, you have to PRINT OUT the form, 3-hole punch it, and fill in the section listing your changes and what line number, and place the document in the "resubmission" slot outside his door, and the cpp file back in the "resubmit" folder.

What for? I don't know. We're not an ISO company, and nobody ever looks at or needs any of that documentation. The best we can figure out, is it's masturbatory material for some kind of weird documentation fetish I guess some old guys have.

Gen Y
Tuesday, July 13, 2004

Good grief.  This man is living in the past.

Ged Byrne
Tuesday, July 13, 2004

Without a coding standard, I doubt you could get much accomplished in a code review.

You *do* have code reviews, don't you?

Derek
Tuesday, July 13, 2004

Yes, he's a prime example of Old Fart.

:D

muppet from madebymonkeys.net
Tuesday, July 13, 2004

I worked for a really really big company that shall remain nameless.  The checkin process was extremely long (but necessary).

1. You had to unit test you code thoughly.
2. You had to document the test data used.
3. You had to print out all the code in the module you were changing.
4. You had to call a code-review meeting where all principle players for that module were called in.  You could find there names at the top of the module.
5. Make any changes they suggest, rinse and repeat.

Doesn't seem all that unreasonable right?  Well the code was COBOL and the printouts were 200 pages long printed on very wide paper with very small print.  You printed a copy for each person in the meeting.  You submitted your print job and it was printed 500 miles away on a special high-speed printer and overnighted back to you.  You had to highlight any code you changed in each copy and it helped to ear-mark the pages so they could be found (flipping through 200 pages was a bitch).

The code you're working on might be 30 years old or older and yes, some of the people mentioned in the module still work in the company.  They are now high up middle management and what not working in other countries perhaps or at least many timezones over.  You still have to call them and they'll conference call in on code they wrote when they were 20.  Fun stuff really.

Your code always needs changing -- because everything is done a particular way for a reason.  Make sure you always reference your tables in alphabetical order, for example.  (The reason is to avoid deadlocking the database as well as for ease of finding on table in a hundred).  If your lucky, your changes are simply enough that another big review isn't required.  If not, you have to do it all again.

Almost Anonymous
Tuesday, July 13, 2004

"What for? I don't know"

Because if he makes it painful for you to not follow the standard, you'll follow the standard.

Tom H
Tuesday, July 13, 2004

"The checkin process was extremely long (but necessary)...."

Almost Anon, no it was not necessary. Maybe that's all they knew in the 70's, but with today's software that would hugely bloat development costs, and the company would never be able to compete.

And the code itself would completely bloat since nobody would want to refactor anything or fix something that's quick and obvious, because they'd have to go through all that crap.

Get with the times, old people, your company and job security is going to be undercut by young, agile startups that do the same for a third the cost, while you're still approving the minutes for your daily code documentation meetings.

Gen Y
Tuesday, July 13, 2004

I worked in a group in a big humongous Co. for about 18 years doing a lot of Fortran. I left there about 8 years ago. There was another old-timer who worked in the same group at the same time but he left that Co. 10 years ago.

Then recently he got a consulting job to go back and update some of that old code. Much of it had been written as far back as 1980. He told me he was able to pick up some of my ancient Fortran, read and understand and alter it without any difficulty because we had worked with the same coding standards all those many years ago.

When code lasts 25 to 30 years, you have to think real hard about maintainability up front.

old_timer
Tuesday, July 13, 2004

At a past company, the glue system (it tied the customer support tool, the EDI network and accounting systems together as well as doing the reporting) that our department ran was written to use Access97 (it was access2, then access95, and I was turning it into a distributed vb/sql server app that ran on a redundant array of cheap computers by the time I left). The team leader made everyone write the same way (and he was the only person who was allowed to merge new code into the codebase for quite some time, like the above example). At first, I thought it was rather bogus, but we maintained something in the neighborhood of 100,000 lines of VBA code (it had about 500 different linked tables; some with a couple million rows, 300 forms, about 200 pounds of baling wire and bubblegum and the MDE was about 20mb). Because it was all written in the same style, everyone in the dept could pick up the code and fix any "problem of the day" without spending hours trying to figure out what the code was doing. That is an advantage of coding standards. It did take about 2-3 months for a new coder to get up to speed on the standards. As a department, it was quite egoless.

The disadvantage of coding standards is that it gets in the way of transferring my thoughts into the code. No one has written a DWIM (do what I mean) compiler yet.

At the end of the day, companies (and people) want consistancy and predictability rather than innovation or excellence. Which is also the reason that McDonalds is so popular, they don't make excellent burgers, they do make consistant burgers: you will get the same no matter which store you go to.

Peter
Tuesday, July 13, 2004

"Almost Anon, no it was not necessary. Maybe that's all they knew in the 70's, but with today's software that would hugely bloat development costs, and the company would never be able to compete."

I agree.  It was painful to work there.  COBOL sucks, DB2 sucks, and the whole damn strange-ass IBM mainframe world sucks.

But there is no way in hell they can ever replace any of that stuff and stay competitive.  So they trudge on.  The entire process they have exists to the truding can continue.  They are not a software company, so some young startup ain't going to do anything to them.

What I would have liked to see is them moving towards Java very slowly.  And they'll probably do it.  The entire time I worked there they were working on a large project to bring the entire company, in all the countries it's in, to a single "platform".  Now that they have the base (I can only assume they finished it) they can start really modernizing *new* development.  Much of that code works, and it's not going away.

BTW, I'm not an old-timer.. ;)

Almost Anonymous
Tuesday, July 13, 2004

"COBOL sucks, DB2 sucks, and the whole damn strange-ass IBM mainframe world sucks"

I just had a vision of Fred Brooks downing a few shots of whiskey one late night and firing this off in an email... heh.

free(malloc(-1))
Tuesday, July 13, 2004

If I could only enforce one standard it would be:

"Insert Spaces instead of Tabs"

I don't care how big your tabs are but there's always more than one person chekcing things.  They all uses different tabs.  Some use spaces some use tabs.  No matter how it's viewed things don't always line up.

Sometimes they do, but 95% of the time they don't.

It's such a simple thing.  It's selfish not to do it.


Tuesday, July 13, 2004

agreed.  And I find two spaces work FAR better than a tab to improve readability (ie, deeply nested loops don't end up 3 pages to the right on horizontal scroll).  Most editors can be configured to insert X spaces when you hit TAB, anyway.  And even if yours can't,  [space][space] isn't so difficult.

muppet from forums.madebymonkeys.net
Tuesday, July 13, 2004

How about you just let developers code in whatever's most efficient for them, then use one of the many automated code formatters if you want it to look a certain style?

Dave
Wednesday, July 14, 2004

Sigh...

Talk about lack of aptitude. Using @-comments, raging about the nonsense, and then admit that you doesn't even know what it is for!?

Come on! Aptitude!

Unsygn
Wednesday, July 14, 2004

>>How about you just let developers code in whatever's most efficient for them, then use one of the many automated code formatters if you want it to look a certain style?

The trouble with this is it will mess up your source control.

Tony Edgecombe
Wednesday, July 14, 2004

At a certain bank I'm not allowed to name, coding standards were... anal.

The guy who designed them basically was an idiot and used the control of the coding standards as a stick to beat rivals with. So there was a lot of wittering about things like making people compare values to things. So yes, you'd end up having to write "if (<boolean value> == TRUE)" in C++... scary.

Then he could concentrate on whether there were enough spaces in the code, instead of whether it worked or not. Not entirely unconnected with this attitude could be some MASSIVE bugs which have caused losses of some 100s of millions of pounds.

I ended up writing a perl script to go do it all automatically. Oh yes. That provoked some Expressions Of Unhappiness. Seems it wasn't really "in the spirit" of things to do this using scripts instead of by hand....

Katie Lucas
Wednesday, July 14, 2004

>+++the braces are in the correct places. +++
>
>of course you know that this is subjective.  ;)

No it isn't. There's only one True and Correct way!

void foo()
{
  if (bar)
  {
  }
}

Anything else is EV1L!!!!!!!

Pass my medication nurse
Wednesday, July 14, 2004

actually I much prefer:

void foo() {

if (bar) {

}
}

muppet from madebymonkeys.net
Wednesday, July 14, 2004

with the requisite indentation, of course

muppet from madebymonkeys.net
Wednesday, July 14, 2004

Dave,
I guess you've never tried to work with one of these ugly space and tab together unlined up files at a client's site.  I guess you only work in a nice clean environment on you own machine that you manage perfectly.

Some of us have to go to client's or other machines and still bring up these horrendously ugly files.

qwerty
Wednesday, July 14, 2004

Burn the unbeliever!

Pass my medication nurse
Wednesday, July 14, 2004

"The trouble with this is it will mess up your source control."

No it won't ... just run the standard formatter on everything before checking it in.

NoName
Thursday, July 15, 2004

*  Recent Topics

*  Fog Creek Home