How to Write Software

I've been reading a few articles from professional programmers which I strongly disagree with.
I've heard that static types should be mandatory or there should only be one way to do things. This really bothers me as younger programmers read this and believe it. Still, I read a long time ago (COMPUTE! magazine, I think) that knowing the language is only 10% of being a programmer. This is mostly true, as once you know what you want to do, then getting there is just a matter of time. Unless the language forbids it, in which case either find another job or a scapegoat for your project. Anyway, I wanted to lay down a few general guidelines for programming in the hopes someone doesn't waste as much time finding them as I did.

Design

• First, there are two parts of programming. Design and implementation. Often these get squished together so create libraries of tools to quickly cobble together similar applications. Then pick the best one.

• Don't start a project without a clear end goal. If you don't know where you going, then you will never get there.

• The software design is a project unto itself, which should have the same things every project should have: time, money, personal and respect.

• Software design is not about finding the best way to do X, it's about finding if X is even possible with Y constraints. The code at this point is only experimental, but much of it will find its way into production. Only you won't recognize it as it will have so much error checking.

• You won't know how much time it will take until you are halfway done with the project.

• Once you commit to a design the customer will change the requirements.

• Your code is going to break, factor in tools to help fix it.

Communication

• Communication between project members takes more time and costs more money than anything else, this is why solid communications is important.

• Communication between project members should be done in documents, specifications, etc. There is no better feeling than fielding a question by referring them to page X, paragraph Y in document Z... Especially if they should have already read it.

• Good communication is short and should be more graphical than it usually is. I don't care if it's a napkin, as long as it's readily available to others.  

• I've heard somewhere that any specification longer than a page is worthless. I have to agree.

• Users will obsess on the GUI. Get over it. Even if you wrote the code which will bring peace to the Middle East, the users will never see it and bicker over where a button should go. Use this to keep meddling stakeholders out of your business.

• Don't rely on email, if you can walk over to the other person's desk. It gives you facetime and allows you to practice your people skills.

• Use pictures wherever possible.

Structure

• When structuring you project, try to create small atomic pieces which can be loosely connected. You are not creating a single solution, since you don't know when and how your project will change. Create a toolkit to solve similar problems. You'll be surprised how often you'll reuse them.

• When planning your project, write out every bit of functionality in plain English, such as "Turns the rotor 45 degrees." Then break these down into similar statements until you get something atomic like system calls. Then do a unique sort on every sentence.This will help you reuse your code in various places by finding similar functionality. Then try to get all the nouns and verbs together to form your project dictionary. The nouns will be your data structures and your verbs will be the functions.

• Don't worry about object orienting your code, if it happens naturally then fine but don't try to force a structure on the problem; the problem should force the solution.

• Break the fewest number of similar pieces. This might happen at a lower level than you expect, don't worry it's the best thing that can happen. Assume this structure and develop the design, again.

• Always add a Read Eval Print Loop (REPL) so you can inspect your program from the inside. This usually turns into your testing harness, just save all your little tests.

• Don't reinvent the wheel. Which would you rather have, a perfect bike tire or a wobbly stone circle?

• Don't be afraid of using Unix tools to solve the problem, they solve a lot of problems.

• You should know Unix. I didn't understand programming until I learned Unix.

• You should know Lisp. Every large program is just a primitive, degenerate form of Lisp.  

•   Keep your GUI code separate from code which does something. This way you can make command line apps to test the important parts of your code.
• Use Lint, or something like it.

• Always start programming with a “Hello World” programming. Then add small bits and pieces of code and compile and test. When something breaks, you know immediately, you know where, and you remember what it should be doing. Generally I create a function definition and return a (constant) value, compile and run. Add a call to the new function. Compile and run. Then I add some local variables. Compile and run.
  
  

Code

• Don't code over 6 hours, you can't read technical documentation for 4 hours straight why do expect to write it (which is harder) for so long.

• Writing code is writing. Read your code out-loud and if it doesn't sound like something people could understand rewrite, rename or comment.

• Comments are lines of code too, and they must be maintained.

• Group lines of code together into paragraphs when they all are for a single concept, such as making a system call or averaging a list.

• Line up sequences of similar lines so the equals coincide. This makes it easier to read and mentally group.

• Use an editor which auto-indents and on the subject of editors, master your editor and your keyboard. Would you trust a musician who played the piano with two fingers?

• Use the dumbest thing that will work. You may be able to implement this with monadic hyper-widgets, but no one else will understand it. Besides, if it works it isn't dumb.

• Files should act like chapters in a book, everything related to X part of the story goes together.

There. Learn that, and as Conan says, and you can beat anybody. Notice none of this is language specific. There are some points which might be difficult with some languages. And come back and read this again when you can, I'm sure I'll updated it as I think of other habits I have.