code aesthetics
-
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.
-
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." This is rule by committee (aka mob). Do these people also come and go any time and any day they feel like it or are there core hours for people to be at work? If there are core hours, who set them? The answer is Management. You know: the guys that run the company. Obviously a standard should not be rammed down the throats of the workers but if all else fails, then management has to say, "This is our new coding standard. Follow it." The establishment of a standard doesn't mean it will be followed. That has be be done through the code review process which I assume is part of you development process. Reviewers should not accept code that does not conform to the standard. Peer pressure is a good tool for standards compliance. A coding standard is not a static thing. So start with a standard that doesn't cause too much backlash and then grow it. Basic hygiene issues make a good starting point. If you are using C++, rules against using some of the more dangerous C compatability features are candidates. Basic formatting and naming conventions are candidates. Things that cause problems are candidates for a new entry in the standard. There are lots of coding standards on the Internet so pick one you like, modify it to suit your situation and propose it to management. If that doesn't work, then sedition may. In every organization there is a developer that is looked up to by nearly everyone. Recruit him/her. If he/she starts to use the standard that you produced (with perhaps a few changes) in his/her own work and as a guide for code reviews then its use is likely to spread. Again, peer pressure is a good tool to promote compliance. The first objective of a coding standard is to make all the code look like it came from the same company. The second is to make it easier to read and modify. You can't build a perfect system out of defective parts. But you can keep the testers busy.
dilton_dalton wrote:
If that doesn't work, then sedition may. In every organization there is a developer that is looked up to by nearly everyone. Recruit him/her. If he/she starts to use the standard that you produced (with perhaps a few changes) in his/her own work and as a guide for code reviews then its use is likely to spread. Again, peer pressure is a good tool to promote compliance.
Heres the thing ... theres no formal code review process either...I had one person check my code when I started, then after that it appears we're left to our own devices, so its possible the code may get crap in it. that was last year! there no agreement on the way forward on code reviews either (it has been discussed), because people discussing how to do this are scared of hurting developers feelings and I think they're worried the rubbish will be out in the open (IMO).! also management will only do stuff if it costs nothing in terms of resource or cost, and they are quite entrenched in their ways... not sure how I can move forward with that...
dilton_dalton wrote:
If that doesn't work, then sedition may. In every organization there is a developer that is looked up to by nearly everyone. Recruit him/her. If he/she starts to use the standard that you produced (with perhaps a few changes) in his/her own work and as a guide for code reviews then its use is likely to spread. Again, peer pressure is a good tool to promote compliance.
I wish I could say that there was a long-time developer who we could "look up" to and is well respected enough for their word to matter... but the people here seem to have an indifferent attitude. One the newer guys have suggested a similar scheme where we took a section of work and said " we sohuld sit down and take a look to see how can we improve this" in a meeting, but it appears very few were interested. So there are deeper problems than this, and looks like an almost vertical struggle (cue brick wall) ...i'm obviously in the wrong place!
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!
-
:sigh: Here I expel the ultimate wisdom, the mental model on which future generations of developers will build their skills - and you vote me for the cartoon ;)
-
:sigh: Here I expel the ultimate wisdom, the mental model on which future generations of developers will build their skills - and you vote me for the cartoon ;)
-
Hi Scott - thanks for the reply and the information. I forgot to include the info about the languages we use at my location. We are mostly a C++ development group, with some C. The targets are 95% embedded environments (non-Windows) but with some Windows application work for tools (the latter also perhaps using .Net and perhaps C#). That collection of languages and environments will obviously imply their own set of guidelines, yet many coding standard guidelines also crossover the language and environment boundaries. It looks like you have put quite a bit of time into exploring these issues and I'd like to gain from your efforts. I'll be emailing you to discuss this further. I appreciate your help. I am located in the Pacific Northwest and don't make it to Florida too often, although periodically I may head over to Orlando where we also have a satellite development group and also to West Palm Beach (family). Next time I am out I may have to look you up...
You're welcome. Seeing that you are mostly a C++ group doing embedded work, a lot of the guidelines in the FDG won't apply. There are still a lot that do, however. Looking at the book, the following chapters are generic enough where they should still apply:
- Chapter 1 - Introduction
- Chapter 2 - Framework Design Fundamentals
- Chapter 3 - Naming Guidelines
The following chapters apply, but only portions of them:
- Chapter 4 - Type Design Guidelines
- Chapter 5 - Member Design
- Chapter 6 - Designing for Extensibility
Chapters 7-9 may apply, but I'm not certain of that. As you mentioned, going beyond the common aspects of the standard you will get in to guidelines that are specific to a language and/or platform. These may cover stylistic concerns (captialization in SQL for example) and may also cover functional concerns (proper use of the Dispose pattern in .NET). At this point I would definately recommend creating a set of standards that build on each other. Start with the "core" standard that defines the things that are common and incontrovertible. Then layer the language/platform specific standards on top of that as separate documents. This should allow you to keep the documents focused without becoming unwieldy. Feel free to email any time. I've been playing in this space at varying degrees over the last 15 years and I'm more than happy to share whatever experiences I've learned. If you do end up in the Orlando area definately let me know as it's only about 1.5 hours away from me (and I know the area fairly well since that's where I grew up). I'm not on the WPB side of the state too often. However, depending on where in the Pacific NW you are it seems like I'm in the Seattle area a few times a year.
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. - Buckaroo Banzai
-
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
Tom deketelaere wrote:
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.
At least it sounds like you've managed to isolate it fairly well.
Tom deketelaere wrote:
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
Feel free to email any time. I've been playing in this space at varying degrees over the last 15 years and I'm more than happy to share whatever experiences I've learned. 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.) There is also a slide deck (it's short but a lot of the slides have speaker notes) available on my blog from the round-table discussion I usually run on this topic if you want to browse through it. (Go to my public SkyDrive folder link.)
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. - Buckaroo Banzai
-
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!
williamFalconerUK wrote:
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.
Those are certainly some common problems.
williamFalconerUK wrote:
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!)
You already hit on some, but adding to that...there are a lot of different problems you can (and probably will) run in to depending on the size and makeup of the team. Each person feeling that "their way is best" and being resistant to change are the most common from the development team. The best way to overcome this is to get them involved in the decision making process and keep things small. Don't have one long meeting where you try to reach consensus for the entire standard. Instead, break it up into smaller more focused meetings. This is espcially important if you want to deal with the "holy war" type issues (things like curly brace placement, tab sizes, etc.) For those issues (and any issue that generates a lot of heated debate) the best approach I have found is to sit quietly in the room and let the two sides argue for a bit (no more than an hour). Eventually everyone will become so tired of the back and forth that you can step in and suggest a compromise based on what you heard from both sides. That's the key - you need to make both sides understand that you have been listening to the entire argument, that you see the benefits in both options and that you aren't taking sides but merely suggesting a compromise. This doesn't always work but it is relatively effective. When it doesn't work sometimes you either have to mandate a guideline or decide tha
-
I take care to ensure the aesthetics of my code. That spacing and formatting is consistent. I don't care if I'm writing throw away code or production code. The code should always look neat and tidy. Why don't other programmers do the same??? OK, I'm sure there are some out there. And yes, there are code beautifiers, so who really cares, right? What's your thoughts on whether code should look good, in terms of spacing, formatting, structure, etc.? Marc
I think I've yet to meet three programmers on a team who all agree on what aesthetics are. consistent yes, within one coder's code. Which is practically useless. I find algorithm complexity to be far more beautiful than the spacing in the original code- but then again, I can READ CODE, rather than READ COMMENTS. Having said that- you'll always find indentation in my code, because I specifically find I have a problem with remembering to close multi-line groups. Other than that- well, that's all personal aesthetics, and asethetics are *always* subjective.
-
williamFalconerUK wrote:
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.
Those are certainly some common problems.
williamFalconerUK wrote:
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!)
You already hit on some, but adding to that...there are a lot of different problems you can (and probably will) run in to depending on the size and makeup of the team. Each person feeling that "their way is best" and being resistant to change are the most common from the development team. The best way to overcome this is to get them involved in the decision making process and keep things small. Don't have one long meeting where you try to reach consensus for the entire standard. Instead, break it up into smaller more focused meetings. This is espcially important if you want to deal with the "holy war" type issues (things like curly brace placement, tab sizes, etc.) For those issues (and any issue that generates a lot of heated debate) the best approach I have found is to sit quietly in the room and let the two sides argue for a bit (no more than an hour). Eventually everyone will become so tired of the back and forth that you can step in and suggest a compromise based on what you heard from both sides. That's the key - you need to make both sides understand that you have been listening to the entire argument, that you see the benefits in both options and that you aren't taking sides but merely suggesting a compromise. This doesn't always work but it is relatively effective. When it doesn't work sometimes you either have to mandate a guideline or decide tha
Scott, Pretty much you've hit the nail on the head. And you've given some good arguments to take away and use to help things along...
Scott Dorman wrote:
Eventually everyone will become so tired of the back and forth that you can step in and suggest a compromise based on what you heard from both sides. That's the key - you need to make both sides understand that you have been listening to the entire argument, that you see the benefits in both options and that you aren't taking sides but merely suggesting a compromise.
I'm pretty much more of a listener in these things than a talker so what you suggest might be the move that could be made, specially considering the arguments are of the "holy war" type you speak of, and they do end up getting nowhere.
Scott Dorman wrote:
Getting buy-in from the developers is usually easier than getting buy-in from management. Managements arguement is almost always "we don't have the time/resources/budget to spend", which is usually the case. However, you need to be able to show that by not having a standard in place it is harder to transition people from one project to another, harder to diagnose and correct problems, and ultimately leads to a less stable code base. This is, of course, almost all subjective as it is difficult to actually put numbers to any of these concepts.
As for the management thing, I think I'll have the opportunity to talk about this and the other concerns I have with them as a review is coming up. if that doesn't work then maybe one of the other approaches need to be taken.
Scott Dorman wrote:
It usually ends up being a combination. Some things can be defined by one person and then presented to the team; others will need consensus or at least involvment from other people on the team. This is especially important if you have "entrenched" developers who are very resistant to change. By getting them involved, they feel they are being given a voice and included in the process. Sometimes that's all it takes to get them to open up and embrace the new ideas.
This may well be the way forward, if no one else takes the lead, then maybe with the right prep, good information under my belt and a good presentation I could do it...and involvement from the team certainly will help! Once again i'll take all the advice on board, so thanks! :) Also if anyone knows of any good
-
Perhaps I'm more age impaired than you are (eyes, you know), but I just ran a test where I printed a section of code with some lines having as much as 120 characters in them. I used Courier New as the font at point sizes of 10, 9, and 8. In addition, I changed the character spacing to be condensed by 1 point. The page was setup for 1" margins left and right (typical for a document at our site). The net result was that I was hard pressed to get even 100 columns across with the smallest point size. In addition, the readability was severely impaired because of the condensed spacing and the smaller font size. I don't think I could live with more than 80 columns for printing...
Ah, 1 inch margins... An inch will fit about 10 chars so that's where the 20 went. I just tested the crappy ole hp laserjet we got here at work. With no margins, Consolas 8 will give you 129 columns by 81 rows. But like I said, I'm with you. 80 columns is best. That way there's PLENTY of room on the right to scribble notes. I mean, you can stare at the screen only so long ... before you go insaaaaane
-
I can only see about 100 columns (in VS, using 1 screen) CRT's FTW though, they're the only kind of screen that doesn't give me a headache (anyone else have this problem?)
harold aptroot wrote:
give me a headache
My other half has the same problem, the place she used to work did a company-wide rollout of new LCDs as the new standard issue equipment & she just couldn't work on one. Headache would build up over the course of a day & take days to go away. At home we bought a 46" Bravia X which we had to take back too 'coz she couldn't watch it :(( . Luckily, we were able to do a straight-out swap for a Panasonic Viera 50" :-D .
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
-
:laugh: I want a shortcut for adding it to code that does not use it!
John
Vikram A Punathambekar wrote:
I wish VS had a similar shortcut for stripping out Hungarian notation!
Take out the annoying MS "redundant data type - already known from declaration" Hungarian
John M. Drescher wrote:
I want a shortcut for adding it to code that does not use it!
And put in the proper "this prefix indicates how the variable is expected to be used" Hungarian?
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
-
Hans Dietrich wrote:
there are some people who just don't care - to them it's a job, and a clean compile is the best you can expect from them.
For some coders, a clean compile is shippable code.
Deja View - the feeling that you've seen this post before.
Pete O'Hanlon wrote:
For some coders, a clean compile is shippable code.
For some coders managers, a clean compile is shippable code. So painfully true! Try going on holidays & having to clean up the mess after you come back when your boss has shipped the work experience kid's code as release product :mad:
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
modified on Friday, September 19, 2008 2:08 AM
-
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
Mike Hankey wrote:
My biggest pet peeve is no comments.
Don't hurt me! ;P My old employer (where I stayed for far too long) was a real cowboy, never ending cycles of "gotta have this yesterday" & the work was mostly very compartmentalised (i.e. only one person doing any real work on any given project) so I got into some very bad habits. Running my own ship now & having to work with others on a MAJOR project, I'm improving steadily.
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
-
I think I've yet to meet three programmers on a team who all agree on what aesthetics are. consistent yes, within one coder's code. Which is practically useless. I find algorithm complexity to be far more beautiful than the spacing in the original code- but then again, I can READ CODE, rather than READ COMMENTS. Having said that- you'll always find indentation in my code, because I specifically find I have a problem with remembering to close multi-line groups. Other than that- well, that's all personal aesthetics, and asethetics are *always* subjective.
Theodore M. Seeber wrote:
I can READ CODE, rather than READ COMMENTS.
Right there with you, however, I'm learning that I'm in the minority on this one. Another thread (or it might have just been an article - don't remember now) in recent months discussed how programmers tend to "think" in the first programming language they learn. While Pascal was technically the first language I learned, C++ was the first I used to any real purpose. I can "read" C/C++ written by another C++ programmer, quite easily. C++ written by someone who "thinks" in VB is gobbledegook to me, I struggle to follow un-commented VB code and I'm pretty sure that any VB code that I write without comments is indecipherable to a VB programmer! The educational background of one of my colleagues has been very theory-based so he actually "thinks" in pseudo-code - which means it's almost imperative that he write comments first (to lay out the pseudo-code) before he can translate into program code!
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
-
Mike Hankey wrote:
My biggest pet peeve is no comments.
Don't hurt me! ;P My old employer (where I stayed for far too long) was a real cowboy, never ending cycles of "gotta have this yesterday" & the work was mostly very compartmentalised (i.e. only one person doing any real work on any given project) so I got into some very bad habits. Running my own ship now & having to work with others on a MAJOR project, I'm improving steadily.
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
I know working in the "had to have it yesterday mentality" position is hard to keep up with such things as commenting, docs and such but if the time is spent up front you or someone else that has to maintain doesn't have to spend vast amounts of time figuring it out.
T-Mac-Oz wrote:
I'm improving steadily.
Good for you. I don't always do the best job but try to keep up with it. In college my prof was a stickler for commenting and wouldn't except a project unless it was commented so I guess I picked it up early in my career. Mike
Semper Fi http://www.hq4thmarinescomm.com[^] My Site
-
I try to do the same, but isn't this sort of relative, what looks good for one programmer may look like crap for another. Of course some rules are very basic (like not letting code be longer then the width of a normal screen) and should always be followed (I think)
For me aesthetics is tied to improve readability. Not really how beautiful the code looks. I guess some people code argue that even "improved readability" could be relative also. The good thing is you try code styles with your team and get to a standard that helps everyone better understand the code.
-
Theodore M. Seeber wrote:
I can READ CODE, rather than READ COMMENTS.
Right there with you, however, I'm learning that I'm in the minority on this one. Another thread (or it might have just been an article - don't remember now) in recent months discussed how programmers tend to "think" in the first programming language they learn. While Pascal was technically the first language I learned, C++ was the first I used to any real purpose. I can "read" C/C++ written by another C++ programmer, quite easily. C++ written by someone who "thinks" in VB is gobbledegook to me, I struggle to follow un-commented VB code and I'm pretty sure that any VB code that I write without comments is indecipherable to a VB programmer! The educational background of one of my colleagues has been very theory-based so he actually "thinks" in pseudo-code - which means it's almost imperative that he write comments first (to lay out the pseudo-code) before he can translate into program code!
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
True to a certain extent. Those of use who started out in "no style" languages though, like early 1980s line number basic or Motorola Assembly, can get to the point where we read in any language. It also helps that I had training in a large variety of languages in college; usually takes 2-3 days for me to switch between, and then I'm comfortable again. SQL, VB, Forth, Fortran, Cobol, C-derived, Lisp, single-or-multi threading; there are only so many combinations. And to think it used to be said that anybody who started out in a language with a freestyle jmp or goto instruction was ruined forever! I think it just made me much more tolerant of different styles in the long run- debugging spaghetti code makes you ready for *anything*.
-
Vikram A Punathambekar wrote:
I wish VS had a similar shortcut for stripping out Hungarian notation!
Take out the annoying MS "redundant data type - already known from declaration" Hungarian
John M. Drescher wrote:
I want a shortcut for adding it to code that does not use it!
And put in the proper "this prefix indicates how the variable is expected to be used" Hungarian?
T-Mac-Oz "When I'm ruler of the universe ... I'm working on it, I'm working on it. I'm just as frustrated as you are. It turns out to be a non-trivial problem." - Linus Torvalds
Being that I have written 500K lines of MFC I have grown very accustomed to using Hungarian notation and I like it. Many times if some one sends me a small code sample without Hungarian notation I will add it myself...
John
-
I take care to ensure the aesthetics of my code. That spacing and formatting is consistent. I don't care if I'm writing throw away code or production code. The code should always look neat and tidy. Why don't other programmers do the same??? OK, I'm sure there are some out there. And yes, there are code beautifiers, so who really cares, right? What's your thoughts on whether code should look good, in terms of spacing, formatting, structure, etc.? Marc
My code is beautiful. By definition. :-D
If the Lord God Almighty had consulted me before embarking upon the Creation, I would have recommended something simpler. -- Alfonso the Wise, 13th Century King of Castile.
This is going on my arrogant assumptions. You may have a superb reason why I'm completely wrong. -- Iain Clarke
[My articles]
