Friday, April 30, 2010

Thoughts and Advice, part 0

General advice regarding engineering

Some tenets:
  1. Everything does not need to be a Class. 
  2. When you do use Classes, consider composition.
  3. Keep it simple.
  4. Ask yourself, "Now that I consider this complete, how can I make it simpler?"
  5. Can any reasonably talented and/or experienced engineer read what I have created and extend it/modify it in as little time and as effectively (e.g., regression-free) as possible?
  6. Ask yourself, "Have I separated data from function?"
  7. See 3. (above)
  8. "There are many right ways to do the task" does not mean there are not wrong ways to do the task[2].  If one can say "All things being equal, this is a correct way to do this task", one must remember that all things are never equal, and the solution you are proposing may violate or lay beyond the principles of the existing robust architecture. If it does violate the principles of the existing and robust architecture, it is indeed a bad solution and you probably shouldn't do it.
  9. When in doubt, find two or three engineers whom you respect and ask their opinion. Better yet, get them together and present your idea/solution to them (preferably at a white-board). The act of explanation slows down your thought process, and activates a different part of the brain (you engage in a different cognitive process than you do just sitting there, ruminating). It forces you to clearly articulate and  linearly work through the solution. Then: make an educated best-guess.[3]
  10. If your rebuttal to anything starts with "Yeah, but..", stop and reconsider your argument.
  11. Rationalizing a bad decision does not alter the quality of that decision. While not all bad decisions can be mitigated right now, don't conflate time- and project-management with the idea that "it was the best we could do at the time, therefore it's as good-code as everything else in the system".  Rather, "Yeah, I know it sucks, and we'll fix it when it's opportune; for the moment we have to live with it".

Some fallacies:
  1. Everything needs to be a Class.
  2. Functional programming "doesn't work"
  3. Imperative (procedural) programming "doesn't work"
  4. [software that is used very successfully around the world] "doesn't work"
  5. Everything must be an Object. 
  6. The more complicated it is, the better the system.
  7. "I don't need to explain myself, just do what I tell you."
  8. Picking emotionally immature managers will result in a mature, professional organization.
  9. "Ur doin it rong". (See 7. and 8. above)
  10. Great engineers always make great managers.
  11. Code is a good outlet to demonstrate to other engineers/the world/my mom how brilliant I really am.
  12. "My code will help The Singularity arrive more quickly".
  13. "The names of things doesn't matter - a good engineer should be able to read the code and know what things are". (Imagine an Exception class named "Fred".  raise Fred('there has been a problem') is meaningless).[4]

[1] Project specifications are generally a static 'snapshot' of an evolving business process. The business changes rapidly as the people running the company must respond to changing market conditions. It's dynamic. We are engineers, but we do not work in a vacuum. We must act as engineer/entrepreneurs.
[2] Via Libor 
[3] If you work for a good manager, they'll  understand that part of their job is to help you recover from bad (although reasoned) decisions and failures; they will also understand that it is not a part of their job to try to prevent you from making bad (although reasoned) guesses/failures. []. They should strongly advise you against making unreasoned, and unreasonable, decisions.
[4] _items = items.item.Item.items() and from items.item import Item is also ridiculous. As are one-letter attribute names and attribute names that still conform to 1970's-era 6-character name limitations.  Also ridiculous is code that isn't sufficiently namespaced: import as stitems and import as tritems is ridiculous.  Worse yet is import game.challenges.exceptions as lolufailz. No, really. Don't do that.