Programming Things I Wish I Knew Earlier

theodp writes "Raw intellect ain't always all it's cracked up to be, advises Ted Dziuba in his introduction to Programming Things I Wish I Knew Earlier, so don't be too stubborn to learn the things that can save you from the headaches of over-engineering. Here's some sample how-to-avoid-over-complicating-things advice: 'If Linux can do it, you shouldn't. Don't use Hadoop MapReduce until you have a solid reason why xargs won't solve your problem. Don't implement your own lockservice when Linux's advisory file locking works just fine. Don't do image processing work with PIL unless you have proven that command-line ImageMagick won't do the job. Modern Linux distributions are capable of a lot, and most hard problems are already solved for you. You just need to know where to look.' Any cautionary tips you'd like to share from your own experience?"

Comments

Comment your code

[Nkwe]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do. Remember that comments are not for describing what the code technically does (that is what the code is for), comments are for what the code is intended to do. Try and comment the decisions you made when developing the code, specifically why you took the approach you did and why you didn't use other options.

Re:Comment your code

[Anonymous Coward]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do

I indented the code to make it readable. That's so obvious I don't need a comment to remind me.

Re:Comment your code

[kantos]

Commenting is not enough... you need to make sure you clean up the comments in a file before resubmitting it... dead comments can be more dangerous than dead code... as dead code at least doesn't run... dead comments mislead the person following later into believing a lie a lie that could potentially have major impacts on the software. Lastly... write meaningful test cases... if your tests only prove the happy path, that's OK... but if they prove that the happy path is the only path.. that is better.

Re:Comment your code

[Anonymous Coward]

Commenting code isn't enough, it's just a small part of the design and documentation process. Comments are there to tie the code to the relevant part in your design document, which really is a part of programming people should put more effort into.

Re:Comment your code

[DMiax]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do.

I know, Python right?

Re:Comment your code

[russotto]

Commenting code isn't enough, it's just a small part of the design and documentation process. Comments are there to tie the code to the relevant part in your design document, which really is a part of programming people should put more effort into.

It's been said for years, but it is almost never done. When it is done, it's most often (IME) done _after the fact_ because of some requirement to produce the paperwork. Perhaps it's time to give up on it. Is there a real reason for insisting on a design document, or is it just some sort of self-flagellation on the part of programmers?

Re:Comment your code

[sourcerror]

Think of comments as an API documentation*. If something complicated is going on, I usually include several usage example as well. Just look at the documantation 3rd party libraries, and try to follow that granularity and style.

Re:Comment your code

[TeknoHog]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do

I indented the code to make it readable. That's so obvious I don't need a comment to remind me.

(pun indented)

Re:Comment your code

[ZorroXXX]

If the comments are out of date, then the code has been modified by someone who was too lazy to update the comments.

When code and comments disagree, both are probably wrong. -- Norm Schryer

Re:Comment your code

[gringer]

// the following code delivers cake to the subject

// the above comment explains the joke

== changelog ==
* removed redundant comments

Re:Comment your code

[Thangodin]

If you are new to coding, don't be a bedroom programmer. You are no longer writing a 10,000 line app alone in your bedroom. You may be working on a million line app with a team. Change your habits accordingly. Learn to work with other people.

Programming is one of those things that humans are not quite smart enough to do. This means you. Check your ego at the door. In the early 90's, IBM estimated that 80% of large projects in the industry (one million lines or more) were "abandoned in disgust". This should give you some idea of what you are up against.

Come to work knowing what you are doing. This may mean cramming in your off hours. Don't say that you don't know how to do something. Say that you do and then learn it!

Put in comments where they are needed, and maintain them. You will forget what you were doing within three months. The harder it was to code, the more you need the comments.

Use descriptive variable names. Try to organize your data into conceptually simple variables where possible.

If you have to complicate a mathematical formula by breaking it into sections appropriate for inner and outer loops, put the formula in the comments. It may even be worth putting in an ASCII diagram if you are working with geometry.

If you can't see the bug, it's because you have become blind to the code. Get someone else to take a look. The mistake may be embarrassingly obvious to a new set of eyes.

If speed is a factor, preprocess the data. Offload runtime cycles to preprocessing.

Maintain an up to date user manual for all tools and apps. Add to it as you add features, update it as you update the features.

Avoid magic numbers where possible, and put any magic numbers you do use into defines, again with descriptive names.

If you can, avoid virtual methods and pointers in streamed objects. This way you can bulk load them and bulk write them. Indices often fast enough, or can be converted to pointers if need be after loading.

If you have lots of booleans, consider a bit array.

Try to write reusable code. Code for the general case when possible, but...

Normalize your data and objects. Don't waste memory and time maintaining variables you don't need. Don't repeat yourself.

Your key indexes should be integers, never strings. Yes, I have seen databases keyed on memo fields--they were tragically slow.

If updating an existing project, get the client to sign off on what is not to be changed or fixed, and make certain that the QA department gets this list. Otherwise bugs will creep onto the list that you are not actually required to fix, expanding the scope of the project.

Build test harnesses whenever you can which can be turned on with a simple switch. This will make regression testing a lot easier.

The hard way is more fun

[msobkow]

The truth is that the "hard" way of doing things is often more fun, because you have the challenge of learning a new tool or API. Plus sometimes it's actually easier in the long run because you've engineered a solution for the outer bounds conditions of scalability, so if your application takes off, it can handle the load.

I guess the real issue is that you have to engineer a "good enough" solution rather than a "worst case" solution.

Thing I wish _others_ would know

[melted]

Do not make things super-modular and generic unless they 100% have to be. In 99.9% of the projects no one, including yourself, will use your stupid dependency injection, and logging / access control can be done just fine without AOP. Don't layer patterns where there's no need. Aim for the simplest possible design that will work. Don't overemphasize extensibility and flexibility, unless you KNOW you will need it, follow the YAGNI principle (you ain't gonna need it).

Overengineering can be a good thing

[caywen]

You know, I find that as I get older, I am able to avoid overengineering things a lot better than when I was twenty something. There's nasty effect, though. I'm learning a lot less in depth about systems than I normally would.

Overengineering is terrible for a project, but it often is highly educational.

Comment your data too!

[LihTox]

I'm in a different boat from most commenters here, I think, because I am a scientist writing simulations; some simluations run a long time and create a lot of data which would be costly to reproduce, and what I wish someone had told me early on was that I should comment my *data files*, not just my code. Each file should include the exact parameters used to create it, an explanation of what each column represents, and preferably there should be a way of knowing what version of your simulation code was used to create it. A couple of times in grad school I had toss out months of data after I discovered a bug in my code, and didn't know when the bug showed up and which data was affected by it.

(I'd welcome other advice from simulationists too; I've never had an advisor who was particularly programming-savvy, even though programming was always a large part of my research, and so I always had to make it up as I went along.)

Re:Some tips from a C guy.

[spiffmastercow]

That's essentially what the K&R C book steps you through, and I'd say it's the best programming book ever written (or at least the best I've read). I don't get to do much in C these days, but the stuff I learned 10-15 years ago in C has made me a much better programmer. It's sad how programmers these days give you a blank stare when you ask if you passed something by value or reference.

Version Control

[BluePeppers]

Put everything in version control. Everything. EVERYTHING!

Well. You could skip /home, but I know a roll back of /etc has saved me a couple of times on config upgrades.

Remember that once code is deleted, you can't get it back. However, version control changes that. Version control is one of the most vital tools for anyone developing/working with a computer.

Oh and git rocks and stuff :)

The Truth

[TheCount22]

A few rules of thumb for a startup environment:

1. Don't overengineer! Overengineering wastes time on things that may never be used. Features should be customer driven.

2. Functions and methods should be as small as possible. You should make it an obsession to split methods and functions into the smallest possible components. Only then can you have good code reuse. Don't start thinking I will split it when I need it, you never will!

3. Never ever reinvent the wheel. Reinventing things that exist is overengineering.

4. Don't optimize ahead of time. When I say that I don't mean don't use a hash table instead of an array where it makes sense. I mean don't try to avoid exception handling or function calls or other minor optimizations. If it has an impact on readability don't do it. Optimization always comes last. Often you'll find there are only 1 or 2 "hotspots" in your code. If you spend time optimizing these "hotspots" after your application is built thats when you'll get the best return on your investment. Another gotcha with optimization is using technologies that can't deliver the level of performance you expect. You should test to make sure the underlying components you plan to use will perform as expected before you start coding.

5. Don't cram as much code in a single statement as possible. Every compiler I know about today will produce identical code whether it's one statement or 5 statements. It makes it hard to read so don't do it!

6. Allocate time for testing. No one writes perfect code.You want to give a good impression to your customer so don't skip this step.

7. Make unit testing an obsession. Always add unit tests for new code, it reveals errors in your code. When you find a bug in your code add a unit test to test for it. If in the future someone decides to rewrite some function or method you wrote because it's not elegant enough they will not reintroduce old bugs.

8. Don't rewrite code if possible. Refectoring is almost always easier and less error prone.