There are two very simple ways to improve the readability and maintenance of the software you write. They are so simple they are often ignored in favor of more complicated tools and the various programming methodologies people blather on about. This comes from our human nature to think our own problems are more special and complicated than they really are and from not following the KISS principle.
So how do you improve your software?
By using better names and being consistent. It really is that simple, which is probably why it is overlooked. A development manager might score some points with his boss by switching to Agile programming, having some scrums, doubling the amount of developer documentation or maybe even switching to a whole new platform like Ruby on Rails. But who scores any points by saying, "We're going to do better about naming things appropriately?"
Appropriate Naming
Obviously having a variable named temp_user isn't all that descriptive, but it is an improvement over just temp or simply t. Most, if not all, programmers realize this. However, you will often see variables named clt when they should really be named client, as if those three extra characters were single handedly going to cause carpal tunnel. Your variable names should be as descriptive as possible without being absurd about it. A variable named the_current_user_object_we_are_working_with is obviously overkill. But perhaps current_user_object or even current_user is appropriate.
Naming your functions and methods should also be given the same amount of care. Naming a function fix_client doesn't tell us anything useful, we can only speculate something is wrong with the client or the data and this function does something about it. normalize_client_name is a much better name when you read that all the function does is properly set the case of the letters in the client's name.
The names you choose for your libraries are also very important. This is one of the reasons programmers find Perl's CPAN much more useful than other programming languages' library collections. Things are named and categorized (for the most part) sanely. Need something related to E-mail, check the libraries in the Mail category. Can you guess what Net::SSH , IO::File::CompressOnClose , and WWW::Google::News do? Yeah I thought you could.
If I stumble upon your use of a library called Util , it doesn't tell me anything I still have to go look at the library to see how it fits in with this code. If it had been named something like DB::Util or Client::Utils I would at least know the library is probably related to the database or client.
Consistency
Consistency is another area where you can improve your code base without much effort. If all of your classes contain an initialization method, they should all be named the same. Not initialize in some classes and init in others. Things that should be consistent throughout your code base, not only consistent within a single application. If possible, the source in your department should be consistent with other departments and business units.
Consistency through conventions is one of the main reasons people like web frameworks like Ruby on Rails. I'm not advocating Ruby on Rails necessarily, you can accomplish these same things in any language.
Things that should be consistent:
- variable, function, and method naming conventions ( underscores or CamelCase, but not both )
- frequency and layout of comments
- documentation
- configuration file syntax
- on disk layout of source code, binaries, configuration files, etc.
- installation, upgrades and package management
- language(s) used for development
The point being the more consistent you are in how you build an application the easier it is to get down to the task at hand. Be it new development or bug fixing. Got a configuration file format you like and have already written libraries to parse it? Then use it EVERYWHERE , in every single darn application you build. No one has to learn the new format to start developing, no time is spent discussing which format is better, and another developer in your organization can jump in to fix bugs or add a new feature.
The last development shop I ran we focused on being consistent. 95% of the time we were building web applications that were either used internally by fellow employees or externally by our customers. If you saw the source to one of our applications, then all of our other applications would seem very familiar. One might be a ticket tracking system and the other an accounting package, but the layout, coding style, and use of common libraries let the developers dive right in and not have to worry so much about how this particular app is written differently than the others.
Consistency in your applications also makes refactoring easier. If all of your applications use a particular technique, library, etc. in the same way replacing it with a new tool you have fallen in love with is much easier. If everyone is doing everything even slightly differently, you have to start worrying more and more how the change might impact your code.
I'm definitely a "right tool for the right job" sort of fellow, but mixing and matching tools and techniques for every single application you build is a recipe for disaster. One shop I know (name withheld to protect the guilty) has two developers. One who works entirely in Perl, the other entirely in Ruby. Another application I saw was written mostly in Java, but with a smattering of C# and Python around the edges for kicks. None of these three were chosen from a "right tool for the job" perspective, but simply because those were the favorite languages of the specific developers tasked with those sub-systems. These are obviously worst case examples.
These ideas aren't new, I'm positive I am not the first to use them or even write about them. But I see these two simple rules violated so often by programmers of all experience levels that I felt the need to reiterate them.
