Beware Of Coder

It occured to me, recently, that the professors who shoved buzz-words like "re-usabilty," or "maintainability," or even [shudder] "documentation" onto us repeatedly and often in college may have been on to something. I have just up and left my home of 12 years in Lafayette, LA to take a job in Shreveport, LA where I am currently encumbered with someone else's [poorly written] code. Suddenly, things are starting to make sense in a way they couldn't have made sense before now.
I've been coding since I was 17, when I borrowed a C++ book from a co-worker and that was, as they say, that. Not long after, I set about enrolling in college (University of Louisiana at Lafayette), where I entered into an extensive study of all things mathematical. (I always found it ironic that, while I am incredibly good with programming languages and programming in general, I have never been very good at math. Especially since, when you get right down to it, computer science is just fancy math. I digress, however, as that is a topic for another blog entry.) From day one, "maintenance" was the word of the day. However, due to the nature of things at that level, most programming was a solo affair. It is incredibly easy to maintain something you have written yourself (hopefully), where you possess the "broad view," as it were. You know how the system is supposed to function (again, hopefully), and you know what each piece is supposed to do. It is easy to go into code you have written from #include to return 0; and make changes, because you know all the sub-sections of code that are dependent on that piece. Since the vast majority of the work you do for classes is done by you, the lessons imparted by the professors, while necessary, don't quite click like they should until you've spent two months digging around in foreign code.
I took this job with the hope of the naive, thinking it would be a fantastic opportunity to flex my creative muscles and dig into the technology and use it to build things that I could be proud to say, "That's my work, right there." Well, I was partially correct. It has definitely been an education, but the lessons learned were not quite what I thought they were. So far, I've learned about 16 thousand ways NOT to write software. I've come across VERY few things done well, either. So, I thought I would share a couple of the lessons for the future that I've had to learn with anyone who might happen to cross my path here. A couple things that would have made my life here infinitely easier. My work right now is with PHP / MSSQL, but most of the following applies to computer coding in general.

The Art of Mis-Direction
The longer the chain of function calls I have to trace, the more annoyed I get, and the more time I waste. Functions which call other functions, temporary tables that get accessed once, temporary table chains created through 15 different functions in 15 different files all create havok in your code and are often unnecessary. Keep things simple, and keep related items close together.

Do one thing, do it well
There is an old saying, "Brevity is wit." Not sure where its from, not sure of its original context, but it applies well to coding. Considering that speed is usually our top concern with computer programs, it is often a best practice to adopt a minimalist approach to coding. Make your code do as little as possible, as clearly and simply as possible, to achieve your goal. Bloat is the #1 killer of software (listening, Micro$oft?), and is the hardest defect to fix. If you adopt a minimalist approach from the start, you save yourself many headaches down the road.

Consistency in naming
Class A has member function insert_db. Class B has member function db_insert.
$varname vs.$varName vs. $Varname vs. $VarName vs. $Var_name vs. $Var_Name vs. $var_Name vs. $var_name ....
Consistency makes everyone's life better, and I don't have to spend so much time double checking the format of the variable being used this particular time.

Class Methods
I should not have to dig through 3000 lines of code trying to take an inventory of the methods that a class exposes. Do me a favor and place a nice, simple, concise dictionary of functions / variables that are available for me to use in the comments at the top of the file. This way, i can go in and say, "Oh, it does have a SaveToDB() function, and it returns a string which will tell me the success or failure of the save." The faster I can find information, the less annoyed I am, and the faster I can get my work done.

Whitespace means something
Perhaps my #1 pet peeve when digging through someone else's code. White Space matters! It matters alot. White space is not there for the benefit of the computer / compiler / interpreter. It is there for the human. The reader of the code. (Unless you are working in Python, then the interpreter expects the whitespace). white space in a computer program is like a lack of punctuation and capitalization in english you can figure out what is being said eventually but it is annoying it makes you stop to think about the form of what you are reading instead of the content and it just plain looks ugly there are reasons we have conventions and rules it makes life easier on everyone (I *was* going to remove ALL the white space from that, but I can't bring myself to be quite that cruel.)

Comment everything
I don't know why you did something, but I can see from the code that you clearly did it on purpose. Was there something down the line that required this time code in this particular format, even though every other time code has a different format? I don't know, because you didn't leave me any clues. Documentation is not for you. Documentation is for the poor bastard who has to clean up your mess.

...

Those are the ones I can think of for this week. When I think of more, Ill add them to the list.