code aesthetics

[geoffs]

Well, I am heading up a committee of 3 that is going to establish a new standard for future development in our company. Over more than 30 years in the development arena I've amassed quite a bit of my own ideas about what makes for a good standard. Also knowing that just because I think a particular guideline is good doesn't necessarily mean it really is, I'd like to ask you if you could point me in the direction of what you would consider some decent coding standard documents...

[geoffs]

Do any of your developers ever find there to be a need to print sections of code? That is still a pretty good lowest common denominator (80 cols for readability on an 8.5 x 11 page) which makes me hesitate to accept anything greater than 80 columns width in the code.

[Mike Hankey]

I totally agree. I'm not fanatical but like to write and read code that is neatly formatted. Easier to read and follow. My biggest pet peeve is no comments. The app I'm supporting at the moment, although very well written is extremely sophisticated and comments are very very rare, and of course no docs. Though I do not comment every line of code I write I do comment in places where it makes sense. Mike

Semper Fi http://www.hq4thmarinescomm.com[^] My Site

[Marc Clifton]

Pete O'Hanlon wrote:

if only you can understand your code then others will naturally think you're a gifted genius

There must be a phrase for when I can't understand my own code 7 years later. Maybe "gifted jerking off genius" since it's definitely a one-man show. Marc

Thyme In The Country Interacx My Blog

[Marc Clifton]

Hans Dietrich wrote:

to them it's a job, and a clean compile is the best you can expect from them.

That pretty much sums it up. Sadly, a clean compile doesn't mean a bug free execution. "Your code looks like shit, and by the way, I can spot 5 logic errors just by looking at the code". That's what I seem to be saying a lot lately. :sigh: Marc

Thyme In The Country Interacx My Blog

[Ri Qen Sin]

Do not go against Visual Studio's automatic formatting. That's one rule I always follow. :)

So the creationist says: Everything must have a designer. God designed everything. I say: Why is God the only exception? Why not make the "designs" (like man) exceptions and make God a creation of man?

[Scott Dorman]

geoffs wrote:

knowing that just because I think a particular guideline is good doesn't necessarily mean it really is

That's an excellent start. It's important that your standards are a result of quality input from the rest of the team and not designed in a vacuum.

geoffs wrote:

point me in the direction of what you would consider some decent coding standard documents...

I can, but a lot of it depends on your chosen programming language. I really like the Framework Design Guidelines book. It is focused on .NET and designing public facing APIs but at least 90% of the guidelines specified apply to any language. The other one (although more for a really solid reference and background information) is the Ada 95 Quality and Style Guide. (If you can't find it, email me directly from CP and I can email it to you.) From one of my talks on this: What is a code standard?

• Encompasses all aspects of code construction
• Designed to improve program adaptation and maintenance
• Do not form an inflexible set of standards
• Consistent
• Is not “one size fits all” – different for different languages
• Defines the “best practices” for writing code for your development group
• Must adapt to changes in technology and language

What is a code standard?

• Source Code Presentation (Code Formatting)
• Readability
• Program Structure
• Programming Practices
• Concurrency
• Portability/Interoperability
• Reusability
• Performance
• Globalization

The rest of the slide deck (it's short but a lot of the slides have speaker notes) is available on my blog if you want to browse through it. Also, if you're ever in the Florida area (or any of the east coast southern states) I present at a lot of the code camps and usually have a round-table discussion on this topic.

Scott Dorman

Microsoft® MVP - Visual C# | MCPD President - Tampa Bay IASA [Blog][Articles][Forum Guidelines]

---

Hey, hey, hey. Don't be mean. We don't have to be mean because, remember, no matter where you go, there you are. - Buc

[Igor Velikorossov]

If I may I add my 2c I would normally strongly encourage to have all personnel involved in development familiarised with Microsoft .NET Framework Design Guidelines. These guidelines set out naming conventions, file organisation and many other rules making the code readable and easy to maintain. There are number of resources worth reading, such as follows: 1. published by Brad Adams (founding member of both the Common Language Runtime, and .NET Framework teams) a) Microsoft Internal Coding Guidelines[^] - a good start and something I do follow myself. b) plenty of other guidelines[^] worth checking out in a free time 2. Design Guidelines for Class Library Developers on MSDN[^] 3. every now and then Krzysztof Cwalina's blog[^] is a good read too (at least it used to be) Secondly I would strongly encourage the code documentation. Whilst I do perfectly understand that documenting the code has been the bane of all programmers since the day 1 (and I also suffer from it), I believe it is imperative to write documentation. The main rule - explain NOT WHAT the code does but WHY you've written it this way. Again I would strongly encourage to make a habit of documenting (at least) all publicly exposed objects (types, classes, methods, properties etc) using XML documentation. A good start: here[^] and here[^] Because I work with .NET all of the above mainly applies to .NET stuff, yet it could still make sense for those working with other languages/technologies.

[Tom Deketelaere]

We don't print much code (everything is sent by email internaly and such means) but I guess you are right if that happens it isn't as readable anymore. (hadn't given it much thought untill you mentioned it, since it olmost never happens here) I'll keep that in mind and might reduce the number of cols

[Tom Deketelaere]

Scott Dorman wrote:

You will probabbly be feeling the effects for a long time.

Well I'v managed to reduce it to one programme now that doens't need much maintenance or altering, but whenever it does I end up with headache's from hell.

Scott Dorman wrote:

Code standards/style is one of those spaces I actually like to play in and have established them at several of the companies I've worked for.

I'm now in the process of doing the same for a client of us so I guess I'm heading the same direction as you, but I'm shure I'm just a noob in comparison ;P

[peterchen]

The ultimate goal is readable, understandable code with few surprises[^]. Everything in that direction helps. Clean, consistent formatting trains the subconcious to provide additional information without mental effort*: indented == new scope, lowercase = local, gets destroyed when leaving block, and so on. Working on a consistent codebase for longer time likely "looks good" / "looks bad" will be injected when looking at a block of code. That might also explain why people get worked up so much about a specific coding convention: reading another one throws them off their guard. Belowdeck, all "danger!" - signs are flashing, while the captain has to reassure the crew that "waves" are indeed a normal appearance in some waters. *) In my mental model of the programmer, we work at the edge of the "7 things one can keep in his mind at a time". Maybe to be a great developer that need to be 8. Pair Programming extends that to maybe 11. "Without mental effort", in this setting, means: not clogging up your first level cache.

Burning Chrome ^ | Linkify!| FoldWithUs! | sighist

[WilliamFalconerUK]

Scott Dorman wrote: Code standards/style is one of those spaces I actually like to play in and have established them at several of the companies I've worked for.

I'm currently working for a company where coding standards are talked about but there has been no agreement on a definitive guideline. The result of this being that each person has their own way of doing things, leading to the problem that the code can be difficult to understand and maintain. It also appears that theres resistance to any move to try to standardise, the reason being that the people involved have their own opinions so we get nowhere further with the discussion. Another excuse given is theres "no time" to sort things like this out. The Question I've got for you is this; when you have implemented such standards in existing development teams, what kind of hurdles have you encountered? and how did you manage to overcome them? I'd like to see if theres an approach that could be taken to get a bunch of developers (and their managers) who are set in their own ways to agree the standard and stick to them (not that I'm in a position currently to push for this, but who knows!) Also, reaching an consensus on the standard vs someone taking responsiblity of the standards, which of these might be a better approach? Any thoughts from anyone on this are appreciated.

Billy. "Duct tape is like the force, it has a light side, a dark side and it holds the universe together!" - Anonymous my holding page..more coming soon!

[Tom Deketelaere]

You might be better off asking scott this (reply to one of his posts) since he has alot more experiance in this than I have. I'v had the luxary up untill now to be at the start off it all and not having to agree with anyone (it was only me ;P )

williamFalconerUK wrote:

nother excuse given is theres "no time" to sort things like this out

Make the time because it will save you alot of time later on.

williamFalconerUK wrote:

approach that could be taken to get a bunch of developers (and their managers) who are set in their own ways to agree the standard and stick to them

Take an old programme/code (without comments or something) from them (written at least a year ago) and ask them to change something. Do the same but with code with comments and standerds and show them how much faster it can be.

williamFalconerUK wrote:

Also, reaching an consensus on the standard vs someone taking responsiblity of the standards, which of these might be a better approach?

In my (humble) opinion only one person should be responisble for the standerd but all should contribute (discusse best way)

[shubumpkin]

The defining of a standard is more important than what the standard actually states. The end result is consistency. In large organisations it can be difficult, the key is to involve everyone in the discussions. You want to come to a common consensus and then implement it rapidly. It might take a long time to reach a consensus, but lots of interesting things will come up. Also it is important to make it clear that the guys doing the coding are responsible for defining the standards, the manaqers should act as trainer and enablers making sure new recruits are aware of their role to maintain, follow and help develop those standards. You must make it clear that you are not trying to tell people how to code! Any decent programmer should secretly love the thought of working with and developing standards even if they oppose resistance to it initially. The key is to highlight the fact that they are responsible for the definitions, its not going to be a management decision forced upon them. A good way to start is to have some collaboration perhaps on a wiki. Thus allowing flexibility in the generation of the standards and also to help get people involved. Ultimately 1 person has to be accountable and responsible for managing the "released" standards. Also it is good to start with something. Find a good general standard and get peoples feedback on it, then try to implement it. Well I hope that gives you a few ideas. It is more of a cultural shift you are trying to achieve. Working from, maintaining and constantly improving standards is a hugely powerful way of working. It is imperative for any company to focus large amounts of time working ON the way they do things rather than constantly firefighting - working in it. The "we just haven't got time now, we're too busy" scenario never ends. The key is to offset the short term, with a much longer term vision! Steve O'Brien A successful person isn't necessarily better than her less successful peers at solving problems; her pattern-recognition facilities have just learned what problems are worth solving. www.newicon.net

[WilliamFalconerUK]

Thanks very much for taking the time on this post, it's given me a lot of food for thought! We have a wiki in our department, but this is not being used for standards(at least as far as I know!), so this may be a good place to start. I'll take on board what you've said and think about what the next step is. You mentioned a cultural shift, there are several things here that need to be shifted culturally here (IMO) and the above is just one of those.. there are loads of other things also need to be looked at, but I won't moan about those! Cheers,

Billy. MCPD Windows Developer "Duct tape is like the force, it has a light side, a dark side and it holds the universe together!" - Anonymous my holding page..more coming soon!

[Steve Naidamast]

Years ago when mainframes roamed the Earth, we developers took great pride in developing legible, neat code. In fact, style was paramount to serious developers since it set them apart from those that had no serious interest in the field. Code legibility was and still is the "mark" of what we used to call the "Super Programmer". Such a developer was one who was not the most technically detailed in knowledge but instead a developer who understood the natural flow of systems development and could design and implement a properly functioning and efficient system using nothing but the memories of patterned experience. Today, I find most developers don't really care how their code looks as long as they can clean it up with the IDE's built in formatters. Unfortunately, the only thing such tools can do is indent code neatly. They cannot declare your variables of method names in a consistent and understandable manner. They cannot develop clean methods that are solid and they cannot repair poor setups with respect to method and class order along with "locals of reference". Today, a developer who can seemingly regurgitate an 800 page text on his or her's preferred development language is now seen as the "Super Programmer" of a group. However, in my experience the best that such technicians can seemingly accomplish is that they "vomit" quite well which impresses management unendingly. Few of these people though, have ever put a major system together and seen their implementation function with few or no errors. I have and still do... The problem is most technical managers today are enamored by this new breed of technician who only seem to perpetuate the messes that management has encouraged in systems development the result being the long-standing and unfortunate hallmark of IT inefficiency, poor results, and failed project implementation...

Steve Naidamast Black Falcon Software, Inc. blackfalconsoftware@ix.netcom.com

[Zhat]

Raises Hand I've been know to reformat entire pages of code, and totally forget why I was there in the first place...

[shubumpkin]

Hi Billy, No problem at all. This is an interesting and sometimes frustrating topic. It requires large amounts of energy and you need management buy in. Sometimes training courses can inspire change. Alternatively start your own company with your own culture! One of the reasons Toyota is so successful is because they pay so much attention to their company culture. Plus processes and standards are not used appropriately in many organisations, where they become stuffy, and inflexible and even seems to inhibit work. On the other hand if used appropriately they can act as steps on the stairway to perfection. You end up getting so ahead of your competitors that their is oceans between you. As is the case with Toyota. If you find this all interesting i would recommend reading the E-Myth by Micheal Gerber (or the audio book) and/or the Toyota way, this is especially useful if you are considering starting your own business.

Steve O'Brien A successful person isn't necessarily better than her less successful peers at solving problems; her pattern-recognition facilities have just learned what problems are worth solving. - Ray Kurzweil www.newicon.net

[stephen hazel]

I'm a firm believer in the 80 column limit myself (I, too, am a code nazi). But pick a different font and you can easily print 120 columns on even the crappiest of printers. Consolas is your friend.

[stephen hazel]

And if the code was CLEAN, you could spot 5 -more- logic problems...