How Not to Code

I'm doing this for my own sanity It's my hope that one day, I won't start a new job and be faced with a mountain of unmaintainable code Some bits to cover first Mostly I do Python, but these guidelines apply to any object-oriented language including: PHP CSS/SASS/Less Ruby Perl C# C++ Objective C Java So, lets get started Here's an easy one: Short Variable Names jimi = User(lgn="jhendrix") ani = User(lgn="adifranco") van = User(lgn="vmorrison") joan = User(lgn="jbaez") john = User(lgn="jlennon") cck = Cake(flv="chc") vck = Cake(flv="van") for u in (jimi, ani, van, joan, john): if u.fflvr == "chc": u.eat(cck) else: u.eat(vck) jimi = User(login="jhendrix") ani = User(login="adifranco") van = User(login="vmorrison") joan = User(login="jbaez") john = User(login="jlennon") chocolate_cake = Cake(flavour="chocolate") vanilla_cake = Cake(flavour="vanilla") for user in (jimi, ani, van, joan, john): if user.favourite_flavour == "chocolate": user.eat(chocolate_cake) else: user.eat(vanilla_cake) Huge Frickin' Files If your file is longer than 1000 lines, you're making my brain hurt. Javascript They're all the same idea It's a convenient place to find everything I need Where else should I put all of this? This is a really big model Excuses Large files are a nightmare. They become a graveyard of "stuff we think we might be using". No one ever wants to go in there and no one knows what that file does. Reality Break your code up into sub-modules with descriptive names. Stop using kitchen sink modules. Find (or make) a place for everything. If one model alone is too big, you might just have to make an exception, but monitor it closely. Got a Better Idea? This one may not be so obvious. Most classes should fit into files <500 lines long. Limited Models, Great Big Utils ( This is all-too-common ) # models/cake.py class Cake(object): def __init__(self, flavour, icing): self.flavour = flavour self.icing = icing # utils.py def cake_bake(cake): while cake.temperature < 180: cake.temperature += 1 def eat_cake(user, cake): user.cakes_eaten.append(cake) user.full = True Not Awesome Be Maintainable # models/cake.py class Cake(object): def __init__(self, flavour, icing): self.flavour = flavour self.icing = icing def bake(self): while cake.temperature < 180: cake.temperature += 1 # models/user.py class User(object): def eat(self, cake): self.cakes_eaten.append(cake) self.full = True This next one? it's often the cause of that last one Related! Copypasta + Underscores = Badness def compress_html_file_bzip2(file): # Does just what you think def compress_html_file_gzip(file): # Uh-huh def compress_html_file_7zip(file): # Seriously? def compress_text_file_bzip2(file): # Ok, now you're just being crazy. class CompressableFile(file): COMPRESSION_BZIP2 = 1 COMPRESSION_GZIP = 2 COMPRESSION_7ZIP = 3 def __init__(compression=COMPRESSION_BZIP2): self.compression = compression def compress(self): if compression == self.COMPRESSION_BZIP2: # Do bzip2 compression elif self.compression == self.COMPRESSION_GZIP: # Do gzip compression elif self.compression == self.COMPRESSION_7ZIP: # Do 7zip compression else: raise NotImplementedError() myfile = CompressableFile() # Uses the default (bzip2) myfile.compress() myotherfile = CompressableFile(compression=CompressableFile.COMPRESSION_GZIP) myotherfile.compress() See what I did there? Redundant Naming Schemes class Cake(object): def __init__(self, cake_flavour): self.cake_flavour = cake_flavour chocolate_cake = Cake("chocolate") vanilla_cake = Cake("vanilla") print(vanilla_cake.cake_flavour) Redundancy is not Awesome ...when you start passing these things into methods It gets much worse... def eat(usr, ck, flv): usr.eaten.append((ck, flv)) usr.full = True How is anyone supposed to guess what ck and flv are here? Better Use frickin' objects! You can be descriptive class Cake(object): def __init__(self, flavour): self.flavour = flavour chocolate_cake = Cake("chocolate") vanilla_cake = Cake("vanilla") print(vanilla_cake.flavour) Without being pointlessly verbose Everyone thinks that theirs is the exception Don't Reinvent the Wheel Time Energy Not to mention the stuff you hadn't considered Mistakes It Makes Your Code More Readable! Most importantly... Say you want to add an API server to your site... Write Your Own Use a Standard Library Option 1 Option 2 You don't get any of those handy benefits But you do get *exactly* what you want, and maybe a sense of satisfaction ...until something breaks They'll just have to figure it out. What about new hires? (almost everyone is wrong) Last one, and this is important How? In addition to those handy benefits, you get: Error messages you can google People you can hire who can work immediately Your code works with other software out of the box If someone quits/dies or is fired, you aren't screwed. Unless: Generally, it's best to go with a standard The options available suck Your needs are extremely specific Write one and release the code! But do your research and talk to your community to be sure. Next up: Redundant Naming Schemes You can find me here: Thanks http://danielquinn.org/ http://gplus.to/danielquinn @searchingfortao Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Final Thoughts - The Zen of Python, by Tim Peters Example Clarity The Core Premise Performance Hardware is cheaper than people The Simple Truth Find out if the project framework/environment (Django, CodeIgniter, Drupal, Rails, etc.) has a preferred method of doing what you want to do, and use it. Deviating from established norms should only come after considerable thought. Know your environment I don't think that word means what you think it means. Comments Comments are for quick explanations of what's going on, not a play-by-play of what your code does. If you have to explain what your code is doing, your code isn't clear enough. http://en.wikipedia.org/wiki/Anti-pattern#Software_engineering Further Reading Why? This stuff just never goes away and they just don't teach it in school. Reddit made me do it Or for kittens. Whatever gets people to listen How Not to Code This stuff has got to stop Daniel Quinn