Slashdot Mirror
What Workplace Coding Practices Do You Use?
Agent_9191 asks: "Recently I've been promoted to what essentially amounts to a project lead role for every project we do, in house. Since my company has run for the past 35+ years with no form of central IT department, there has been no standards put into place for developers to abide by. One of my tasks is to set up standards in how projects will be implemented and produced. Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code. I've come across some documents in this area from a few sources (of course can't remember them off the top of my head). What practices/standards do you use in your workplace?"
Tell them to use comments in code, and be sure that they make them good comments.
I don't preview or spellcheck.
Has several excellent articles on the subject This is about as good of a starting place as any.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
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.
Code, Hardware, stuff like that.
In my job as a web developer in a healthcare system, I'm all about evolutionary prototyping and other interative 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.
I like to think of it as "don't ask, don't tell" :D
got sig?
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.
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!
In the future, I would want to not be isolated from my friends in the Space Station.
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.
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.
Help Fight SPAM today!
The importance of a single language standard can't be overstated. Ever since my company switched to LOGO I can understand my co-workers' code at a glance.
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).
You can never go home again... but I guess you can shop there.
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.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
I work for one of Activision's subsidiaries and this is what we use:
int* gpiGlobalInt;
int FunClass::GetSize(int _iArg1, bool _bArg2)
{
bool bBool;
float* pfFloat;
static int siStaticInt;
for(;;)
{
}
}
Seems to work out well enough.
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.
"You know you're narcissistic when you quote yourself in your sigs." -- PRoPAiN!
GetOuttaMySpace - The Anti-Social Network
From my experience managing many multi-million line code projects for many years, its the tools (source control, bug system, langauges) and a standard documentation templates (market requirements doc, product requirements doc and detailed design document, unit test document) that are more important to standardize than coding guidlines. Sure everyone should follow a good variable naming convention (hungarian or equivalent) and heavily comment each function's purpose, but beyond that you can waste a lot of team time on arguing about idententation, and micro-commenting guidelines.
Also key is a standard process of developer peer reviews. All developers should have peers review specs. New or mediocre developers should have their code peer reviewed. Proven developers can be excused the code review but not the spec review.
You seem to be asking more about the basics of Project Management than specific tools. For a fair overview of the subject try this in Wikipedia. The grand-daddy of Project Management for software development is SEI-CMM.
The smartest man in the whole, wide world really don't know that much. - Mose Allison
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.
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.
Yeah, standards are great.....we've got lots of them :-)
-Chris
--an unbreakable toy is useful for breaking other toys--
- Get a development database, a testing database and production database. Yes, you need all three.
- Write a few docs explaining each system. Make these are detailed as you possibly can. (This will save you weeks in the long term)
- Use software revision control. CVS, VSS, whatever, use one.
- Use a bug tracker. BugZilla, Jira, CityDesk, whatever, use one.
- Use whatever coding standards the language reckons you should. If java, use sun's standards. If microsoft, use their standards.
- 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.
- 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.
- Have a naming standard for database tables. This will make your life SOOOO much easier.
- Read thedailywtf.com and don't do anything that is posted there.
- Write specs for your new developers. Please write specs for your new developers. Don't just say to them 'fix this up'.
- Make sure code isn't hard-coded to a particular directory. Everyone does this. Fix it. (Might be part of step 7)
- Create your own standard config files.
- Have code reviewed by peers. Don't be a bastard but be nice when picking on people's code.
- 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.
- 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.One word.. doxygen. 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
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:
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.
Wake up - the future is arriving faster than you think.
I find that a good standard for code reviews is to assume that the programmer knows what he's doing and I don't try to push my political agenda in them. If you want to have a passionate argument about hungarian notation or putting braces around if statements that only execute a single line of code, the code review is not the place to do so. If you think a data structure he used isn't up to the volume of data you'll be running through the system, THAT's something to bring up in the code review.
You can require comments in your code all you want, but I find that you inevitably get something like this: "a++; /* Add 1 to a */" With no indication anywhere of what A is or why you would be incrementing it there. I would propose power stapling the offending programmers in such cases, until they learn not to do that anymore. I would say remedial English classes, but even I am not THAT sadistic.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
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.
boakes.org
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.
int beersOnTheWall = 99;
while(beersOnTheWall>0) {
me.chugBeer();
beersOnTheWall--;
System.out.println(beersOnTheWall + " bottles of beer on the wall...");
}
I would write people up, and see that it was reflected in there perfomance review.
You work for me, you do it my way. If you think your way is better, present it to me and tell me why. "Cause it's the way I do it " doesn't count.
I'll train you, I'l give you time to set up your editor so it automates whatever you need automating. I'll mentor you, have other developers mentor you. But there is a line where I expect the developer to be up to speed.
The Kruger Dunning explains most post on
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
enum is your friend!
...
;-(
enum {LOAD_DATA, SAVE_DATA, DESTROY_DATA}
Paul B.
P.S. And of course my all-caps enum values were considered too lame by lameness filter...
heh
"MY APOCALYPTIC TENOR HAS NOT BEEN DISPELLED!" - T-Rex, qwantz.com
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.
I have discovered a truly remarkable
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
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
http://saveie6.com/
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.
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.
Perhaps someone broke in and fixed the code.
how to invest, a novice's guide
I know what you mean about coding standards. I have worked in so many places and have been asked "Do you have any coding standards that we can use". So instead of carrying around stacks of documents, I have placed them all on one site. Go to Delphi Coding Standards this is a Delphi coding standard I follow, but I'm sure you can apply it to all languages as required.
I'm sure many others here have already gone on and on about coding practices, so I'll go in other important directions.
:)
Beanbags. Very useful. Especially when you've got those incredibly stubborn bugs, and feeling careless and jumping about and falling. *grin*
Food and drinks (coffee). Increases productivity greatly.
I've also appreciated how the QA team is ideally located in separate offices from devel. Things get pretty messy.
(copy paste as much as possible)
C# - The C# Coding Style Guide, 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. .Net Coding Standards, part of the SDK. This is not comprehensive though, like the C# doc mentioned above.
VB -
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)
Life is just a conviction.
This is a subject near and dear to my heart. I have a history of coding in small shops, from 1 to 7 programmers. I currently work with two other programmers at a company that has had 4 programmers before us that are no longer available to us. My coding style is very different than my coworkers'. My code is very dense, with few comments, because I believe the code is the comment, and frankly, I think if a compiler can understand it I should be able to also. But that's not important here. I think it is useful that we all have different coding styles. In an environment like mine that has only a few players we learn each others style and know who did what just by the way it looks. It's also nice to see where one person has modified another person's routine.
I love good variable names and statements of purpose and all that, but I think pure conformity is counter productive. Whatever guidelines you put in place, if you allow for some differintiation between authors it will help with the debugging later.
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.
"How to Do Nothing," kids activities, back in print!
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
Build it, and they will come^Hplain.
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-
I have recently aquired the book "C++ Coding Standards - 101 Rules, Guidelines, and Best Practices." ISBN 0321113586 or http://www.amazon.com/gp/product/0321113586/103-00 42056-9954216?v=glance&n=283155/
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.
" and finding out that those things no longer apply because somebody changed a 1 to a 2."
Comments lie. Code never lies.
Need Mercedes parts ?
I achieved a similar thing in my company by setting up a wiki (I started with Twiki and then we changed to Confluence) with a basic skeleton that I wanted have fleshed out. I even got our developers to define the skeleton, they all knew what we needed, code guidelines, review methods, development procedures etc. Now all I have to do is spread the word about the existence of the wiki and watch it emerge!
Steve McConnell's Code Complete 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.
You should also worry about development practices. Just having good coding pratices will not gain you much in the way of robust and easily changed systems. Having good development pratices will.
Specifically, I'm referring to having a complete system of specifying the requirements for any system. Too many coders these days start a project by hacking up the first thing they think is necessary, then the second, then the third, etc. While this ends up working out for most small projects, big projects can quickly become unweildy. Not to mention, if you bring in a new developer after years of working like this, the learning curve for that developer is very steep.
Enter Hatley & Pirbhai's Strategies for Real-Time System Specification. In this book, the authors outline a set of strategies for developing complicated systems and making them as robust as possible. Now, you may be thingking "Who are these guys and why should I care what they have to say?" Well, they used to work at Boeing and they developed their strategies while working on designing a plane. (I think it was the 777, but I could me wrong.)
You should definately read the book, but the strategies they present basically boil down to defining the whole system from the perspective of what, how and when--separately. Here's how it works:
This may seem like overkill, but it's not. I've been working like this for a few years at college now and it has huge advantages. Development tends to go faster, problems can be fixed faster and--most importantly I think--new developers can sit down with the specifications and get up to speed very quickly.
Overall, I think using strategies like Hatley and Pirhbai have developed is far more important than all the coding practices and code commenting in the world.
Of course, YMMV, etc.
--JamesSnowden and Manning are heroes.
Hungarian notation puts an unenforced comment into every variable name.
the problem is not when you look at intPositionSensorReading but rather when it has been changed to a decimal, or when you need to change it to a decimal suddenly you are either wasting time editing every piece of code using that variable. or you cause incorrect comments to be all over the code.
IFF VB would enforce and automate hungarian notation as an option it would be useful (i use VB as the example because it is the only place i have run into Hungarian Notaiton)
More HERE
Snowden and Manning are heroes.
In addition to that, don't hard code values into variable names such as making a timer variable called fifteenSecondTimer.
Read and apply the Pragmatic Programmer.
I see a lot of comments in this thread about coding practices and the like. That is fine, but I think you would do well to think about practices that matter more. You have indicated that your environment really doesn't offer much of an IT infrastructure, which means that you will more than likely play an appreciable role in many of the following processes: requirements management, quality, change management, project management. There may be many instances of your behavior causing projects to succeed or fail, and they will have nothing to do with whether your people are commenting their code.
If you can, put together a process that specifies how all of you can define a product, start a project (get a suit to sign off on it too), deal with changes in requirements without tanking the project, assure quality, and ship. The code will take care of itself because it is the only thing you will have a decent amount of control over. Everything else is cross-functional, which adds a great deal of difficulty -- hence the need for policy.
Just remember the "ship" part. Don't get stuck too long in defining a process because none exist which are universally indicated, completely effective, or free from ruinous meddling and circumvention. Worry more about what can keep you from shipping and try to set a policy that will prevent those things.
And most of all, watch your cornhole -- technical leads are sh*t magnets.
The most important thing is AUTOMATE everything that you can.
We run a cycle where we do an automated checkout every 15 minutes. This is compiled and the checks below are done on all packages that have been updated or which raised errors the last time. Every three hours we do a zero base checkout and run tests across everything including running all unit tests. We also then do a complete construction of installers etc. for the products we ship and run tests on that (rather than in the developer environment). We also checkout across multiple platforms and run the unit tests on these (this is a bit more irregular). The results are collected on a company internal website and errors cause a real-life set of traffic lights to turn red (everyone can see them).
The things we automate include:
There is more to testing than this but this certainly deals with the low level coding stuff well.
If code is written well, it should have few comments as the logic should be fairly obvious. In the case of if (x == 456), this should really be something like "if (STATUS_BUFFER_FULL == statusCode) ..." now it's obvious what is going on. Descriptive variable names and method names mean less comments are needed.
Hungarian notation has its (extremely limited) uses. The reality is that it turns code into garbage. Go ahead, read aloud the lines of code below.
// the old c style
if(cur == last) rec->tag = name;
// camel case
if(currentKey == lastEntry) Record->keyTag = userName;
// hungarian
if(iCurrentKey == iLastEntry) prRecord->m_pszKeyTag = pszUserName;
Now imagine discussing them with your coworker. Imagine thinking in your head "What should I do if prRecord->m_pszKeyTag is NULL?" Humans are good at symbolic manipulation. Giving something a name makes it easier to deal with. Giving something a label that cannot be easily manipulated in language (spoken or in your head) severely hampers the ability to think it through.
The argument for Hungarian is usually "but it lets you know what the variables are". This is the maintainance programmer argument. This argument rarely makes sense in reality, unless some very bad programming is involved. First of all, if you do not understand the current code you are about to modify, you should *not* be modifying it. If your maintainance programmer is just going to have a look at two lines of code, add a third in the middle, and hope for the best then you are truly fucked. He has obviously not understood the code enough to know what the consequences of the modification will be. The reality is, if your current logic unit is such a monstrosity that looking up the types of your variables is a burden, and your variable names are so poor that it is insufficient to infer at least a basic understanding of what is going on without having to resort to prepending types, you should probably step away from the keyboard, turn off your computer, and tell your boss that you had an epiphany and will be pursuing a career in French fry development.
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
One, when I start plunking away at the keyboard, most of my ideas have been muddled through and I'm not wasting time fumbling through books and websites to find answers. I can also note what ideas did and did not work. Also, since I am typically juggling mutliple projects, it helps me keep track of what I've done and what I have to do.
Second, I've learned to keep it for review. Basically, I learned at my last job that documentation can save your butt, especially when working with nurse manager who still can't find her archives folder in Outlook or trying to explain how archaic software works to management when nobody has even looked at the source code in 7 years. Its a picture into my brain and its a log of where things have progressed for a give project.
Third, my notebook has served me are my only way to figure out what the heck I'm working on. Essentially, I've always been given a massive system to rework/hack/redesign that nobody else bothered to figure out. My notebook is my only guide to solving problems, since its my only reliable reference.
Fourth, a journal can double as a weekly to do list. Alot of times, I have so much crap going on running my system that I forget what the hell I was working on. So, I often write down 10 projects or assignments I need to do within two weeks and cross them off as I go along.
And finally, it keeps me from having to write the same things twice. Often, I can use code snippets, data structures and old work flow schemas in other projects. that's really helpful when you're up until 12-1 in the morning hammer away at some God awful perl script and you need to get everything finished by the weekend.
** PACS and RIS stand for Picture ArChiving System and Radiological Information System, respectively. They are two ancillary systems that hospitals now use to save X-ray, CT, MRI and other images of the body.Most standards are relatively meaningless. Indentation, Spaces not Tabs, "All class names must be descriptive", "Comments are required" - really this is all hand waving. Let individual groups figure out what's best for them. And stop thinking like a boss, or you'll find yourself with no one to manage pretty quick.
------ Tim O'Brien
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.
9/11 Eyewitnesses to Explosive WTC Demolition 1 of 2
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/. 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.
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.
Advanced users are users too!
If it compiles, ship it. If it doesn't compile, ship it. If the users complain, ignore them (they are always complaining). If the users complain moreso than normal, work all day and night and fight with QA and the admins and the VPs to get a patch in.
Repeat until app becomes unmaintainable. Repeat furthur. Repeat.
I will be giving seminars on how to implement Sisyphusian Unified Process throughout the year down at the bar. If I happen to be unconcious, please leave me be - that's my "comp time".
Use indent for C and C++
And Jalopy for Java.
Formatters are available for most languages.
Decide on what all of the options are for each formatter and make
a script available that runs the formatter with the appropriate options.
Require that automated formatters be run before code is checked in.
It is easier to read consistant formatting than your favorite formatting.
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:
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:
Good luck.
Mostly these threads focus on comments and naming conventions. One of the most important coding styles I've adhered to for the last decade is to always encapsulate new and delete within a class. This ensures every new has a corresponding delete called when the class's destructor is called. Use C++ automatic variable declarations to control object lifetimes.
The only time I've had a memory leak in the last 10 years was when I had to break this coding standard (eg for library compatibility).
The second most important coding style is to use pointers only when necessary - some graph algorithms need them, and so do some "legacy" C libraries. Otherwise, use references - there in the language for that purpose.
The 3rd most important coding style is use standard library container syntax whereever it makes sense. Even if you write your own container libraries - follow standard library conventions. Makes it much easier for other coders to follow.
After this follow a bunch of useful stuff - eg ensure that meaningful default, copy constructors and assignments are available for your class, use the const keyword wherever it makes sense
On the subject of naming conventions - naming conventions can lie! Tools like doxygen will quickly tell you what a particular indentifier refers to in a particular context. If not, then grep is pretty handy at working it out. However, often one wants to use the same name for type names and instance names - a convention like first letter upper case for typenames, or appended _t can help the addled brain.
Throw open a question now - any good tips for organising namespace names, and macro names to avoid the inevitable clashes?
replace a stupid name with a sensible name:
messages_processed++;
This actually makes sense without the comment.
There are three categories of standards:
;-)
1) First, there are arbitrary choices where uniformity across the company is more important than having a perfect fit for each project.
A perfect example is the choice of information management tools and formats. Unlike an indentation style, a source control or bug database learning curve can be a significant barrier to a developer helping out another team for a few days. It's also important to ease access for non-development personnel. Pick some tools and make everyone use them.
"Every project shall use Subversion as its source control system, BugZilla as its bug tracking system, and DocBook for user documentation."
Depending on the size of your company, the choice of a unit test framework or a build tool might be standardized. Keep in mind the benefit of diversity in these matters, though.
2) Second, there are matters of practice that can be fairly unambiguously stated and checked.
A few examples:
"Every project shall version its acceptance tests."
"Every project shall archive acceptance tests and test results for every software release."
"Every project shall publish a current schedule, updated daily, and a summary of outstanding defects, updated at least weekly, to the IT intranet."
"Every project shall maintain a system of peer review, so that all code must pass by a second pair of eyes within a week of being committed."
"Every project shall automatically generate API documentation."
3) Third, there are matters that may be important but shouldn't be included in your standards.
There are two good reasons for being so picky. First, you want your standards to be as short as possible so people actually read them. Second, you don't want to publish standards that you can't or shouldn't enforce.
An example of a good coding rule that doesn't fall into the first two categories is "Document intent, not mechanics." Everyone should do it, but checking and enforcement should be done among project teammates, not by a higher level of management.
Another example is "Test everything that can break." The extent of test coverage can only be determined by people actually working on the project, so you can't enforce this rule. It's a great rule, but it doesn't belong in your standards.
Since so much attention has been paid in other posts to matters of code formatting, I might as well add my two cents. For languages where there is One True Way, such as Java and Python, there's no good reason to deviate from the One True Way. Is it really your job to point out and enforce the obvious? I don't think so. Let the project managers handle it.
For other languages, such as C++, there are a variety of accepted styles. Uniformity is good, and every project should certainly pick a style and use it consistently. Whether to pick a uniform style for the company is a judgment call. Professional C++ programmers are used to dealing with variety and shouldn't have problems switching when they jump from project to project. For your company the right rule for dealing with C++ projects may be this:
"Every project that uses C++ shall adopt and publish a uniform brace and indentation style."
Or it may be this:
"All C++ code shall be formatted as in The C++ Programming Language, Special Edition."
A final note: Be firm about setting standards, but talk to people first and don't issue any orders that you don't have the muscle to enforce. Find out what people's prejudices are and eagerly defer to them when it doesn't make much difference. Migrating CVS users to Subversion should be no big deal, but if a bunch of stubborn CVS users refuse to migrate, and you fail to make them, all the rest of your standards will go out the window as well. If your authority is shaky, the best way to shore it up is to avoid controversy and issue a bunch of commands that nobody minds obeying
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?
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!
Here's what I like:
:) The team lead can then decide on a policy, e.g. "there will be no discussion on this point, everybody can do it how he/she pleases", "everybody will do it *this* way", something like that.
1. As for code comments, rely on "Use The Source, Luke" as much as possible. Force people to write readable code, so that this actually works. Logical variable names, no unnamed magic numbers, no cryptic constructs. No loop bodies consisting of only a semicolon, e.g. "for(...;...;...);". Comment only on the things that aren't obvious. Any extraneous comments are bound to be outdated by the code, and will confuse more than help.
2. Write down the design in comments in the source files, as a readable piece of prose containing all of the design considerations and decisions. Design of an algorithm goes in the function body, design of a class goes above the class definition. Programmers are aware that designs are often outdated, so when they read them this is not a problem. Having the design in the code has the advantage that you can actually *find* the design for the code you're looking at. There have been too many times where I've been looking for a design document that was "somewhere on the network". Or that I've been looking at a design document on the network that had been superseded three years ago. Having your design under source control fixes that.
3. Build at least every day, or even better: continuously.
4. Automated testing. Run automated tests on every build, if possible.
5. Code reviews. Sit together once a week with one other team member who then reviews all your code for the last week (all of it, based on reports from source control). That shouldn't cost more than an hour or something, it's a good way of keeping the knowledge going around, it works as a very good "desensitization therapy" for those programmers who can't handle criticism, it increases communication within the team because people get to understand each other's work better. The only downside is that there is usually a lot of opposition against this -- I know a *lot* of programmers who don't like to have their code criticized. And there's a very clear risk that people will get into endless discussions about very small details of style ("should there be a space between the if and the parenthesis?") or other inconsequential things. To prevent these issues hogging the review, there should be a formal "escalation procedure", where the issue is passed on to an arbiter (team lead) with arguments from both parties. If a disucssion on an issue seems to go in this direction, either party *or* somebody else in the room whom the discussion irritates the hell out of should be able to cut off the discussion and "escalate" it.
Note that I'm currently working in an environment where we have (1) to (4) implemented. I'd like to have (5), because there is too many crap code being committed, and there's no check on that. It's been all too often that we've had to replace the *entire* work of a team member after he/she left, because the team member had been able to commit crap code without check during all the time (s)he was on the team.
I make sure that every new technical hire to our company reads this book by Kerninghan and Pike. Then, I give them a copy of our coding standards which really just outline the syntatic sugar. If the person was bright enough to get hired, they are more than capable of understanding and applying the concepts presented to them through these two sources.
Read this thoroughly, and try to do the opposite.
disassembly can lie if the operating environment or hardware is bugged (either error or with malicious code)
the only truely trustworthy code is code hand compiled to run on a tube CPU which you have personally blown the glass and formed every tube.
Snowden and Manning are heroes.
Most people who advance coding standards talk about how braces should be put and whether there should be used braces in one-line if's, maybe they even mention the horrible and feared Hungarian Notation. I have yet to find out how any of this *actually* helps understanding code.
Readable code is a prerequisite for understandable code, education is a prerequisite for understanding.
Coding-standards is trying to apply a method of syntax to an education-problem, it's not gonna work. Don't think that coding-standards will give you readability, much less understanding.
My advice is to get a few people with experience, solid, broad knowledge of the language and a pragmatic attitude to sit down and pair-program with the people who write hard-to-understand code and those who have a hard time understanding code that should have been easy to understand.
Let people present idioms, discuss patterns and create a place where "readability" is a code-quality and a goal. (BTW: Don't fall into the "everthing is a pattern"-trap) This is not a coding standard, it's an education of "this-way-works-well-for-this-and-that".
Promote knowledge of the language standard-library, instead of duplicating it yourself. Learn to shun "wrappers". Use the language-features for what they were meant to do, not for insert-really-cunning-hack-here. Model things as they are, instead of cutting coreners or adding complexity.
Check out c2.com http://c2.com/cgi/wiki?WelcomeVisitors it's really a place worth knowing. Read the dialogs, they may not all be truly insightfull but they provide you with excellent examples of what people think about in development and why it's not that easy to do-the-right-thing.
One specific thing i've found is that most people write code by copying (atleast a skeleton) from somewhere else. Accept this, and to give them something *proper* to copy from, short, complete programs -- taken from real situations, Not crappy code-project articles where people try to show off how complicated a technique they can master.
SLOGEN [ http://ungdomshus.nu : Sebastian cover music]
Comments often get in the way of code readability. I often get annoyed looking at comments like these:
// initialize index to zero
// if string is null return an error
// get the next index
index = 0;
if (string == null)
return error;
index = getNextIndex();
Comments should be reserved for describing functions and non-intuitive variables or code blocks.
I find that having naming conventions for variables, classes and functions is very important. Using proper names makes reading the code so much easier and eliminates the need for useless comments like the ones above.
I remember back in my first or second programming course they said, "you should be able to remove the code, read the comments and fully understand what the code is doing". I never agreed with this statement.
More importantly: Don't be too clever.
It's when people try to get clever in their coding that it gets hard to read. And, quite frankly, that's the code that generally breaks most easily.
This sig has absolutely no significance and serves only to take up screen space and waste the time of the reader.
but what if aliens replaced your glass tubes with dynamite when you weren't looking?? it's better to just not code at all, and spend your life hiding in a cave armed with a pointy stick.
I hate Hungarian because you know the type from the context anyway. You don't do addition on a list. You don't do foo[bar] on a real.
A variable should encode everything you need. A variable strSql isn't as useful as selectFoo which tells you what you are doing with the variable. The the variable contains sql is obvious from the context where you care about the contents, and you tells you what it is for where you don't care about the exact contents.
"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...
I don't feel like it...
Have an opinion on all the above but some of your best coders might disagree. And might not agree with each other.
Code reviews for bugs, design, format, readability et cetera are a good way to improve code quality and application quality. Code reviews are very difficult to perform and very difficult to manage.
The idea of code reviews is so old that the older recommendations say you should review before your first compile! Find a newer guideline. The most important guidelines are about the emotions involved in code review. People can get very accusatory and very defensive.
One way of doing reviews is pair programming.
You will find as you go along that many managers and customers simply do not want higher quality if it delays first release. Chew on that.
Think in advance what you will do if you find you have a good coder that nevertheless produces code that is too hard for others to understand. Rather than canning somebody, perhaps you can help the coder to express him or herself more clearly, and help teach the other one to read code more effectively.
Code reading is a specific skill and may be a specific natural talent. That is, different from the skill and the natural talent of code writing.
Code reviewers, testers, managers, and others often have a legitimate need to add comments and/or links to production code ("bug #1234 crashed here", and "I don't understand this", and "90% of the cpu is used here"). It would be good if there were a version-control and text-editing system that allowed non-coders to add "yellow sticky notes" to code -- without breaking the build!
I18N == Intergalacticization
"What should I do if open paren capital R ecord dash greater than capital K ey capital T ag equals equals null close paren?"
If we used Hungarian and I were to ask the question of a coworker, I would of course leave off all the crap (unless it were relevant). Humans are good at that and Hungarian notation makes it pretty easy to spot the "real" name (just skip everything until you get to the first capitalized letter).
You may have a point if you are instructing a coworker in what to type into his editor, but if that's the case you probably have bigger problems with your development team.
My favorite was the entire huge module with only one comment: /* Make sure j != 2 !!!*/
No sign of a variable named j anywhere...